From 08fc8467bc221d0c444567e9527973cccb0c723a Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 25 Jun 2026 22:51:38 +0800 Subject: [PATCH 001/119] Add ask_user_question interaction tool --- docs/architecture.md | 3 +- docs/cordis-catalog/events-and-services.md | 13 +- docs/module-graph.md | 18 +- packages/README.md | 8 +- packages/core/README.md | 2 + packages/core/tool-ask-user/README.md | 18 ++ packages/core/tool-ask-user/package.json | 38 +++ packages/core/tool-ask-user/src/index.ts | 63 +++++ .../tool-ask-user/tests/tool-ask-user.spec.ts | 185 ++++++++++++++ packages/core/tool-ask-user/tsconfig.json | 36 +++ packages/core/user-interaction/README.md | 22 ++ packages/core/user-interaction/package.json | 32 +++ packages/core/user-interaction/src/index.ts | 105 ++++++++ .../tests/user-interaction.spec.ts | 75 ++++++ packages/core/user-interaction/tsconfig.json | 21 ++ packages/support/README.md | 2 +- packages/support/ui-stdio/README.md | 6 +- packages/support/ui-stdio/package.json | 3 +- packages/support/ui-stdio/src/index.ts | 146 ++++++++++- .../support/ui-stdio/tests/readline.spec.ts | 1 + .../support/ui-stdio/tests/ui-stdio.spec.ts | 231 +++++++++++++++++- packages/support/ui-stdio/tsconfig.json | 3 + packages/ui/stdio-agent/README.md | 6 +- packages/ui/stdio-agent/package.json | 4 + packages/ui/stdio-agent/src/index.ts | 4 + .../ui/stdio-agent/tests/built-bin.e2e.ts | 3 +- .../ui/stdio-agent/tests/stdio-agent.spec.ts | 2 + packages/ui/stdio-agent/tsconfig.json | 6 + pnpm-lock.yaml | 39 +++ tsconfig.build.json | 2 + tsconfig.json | 2 + 31 files changed, 1083 insertions(+), 16 deletions(-) create mode 100644 packages/core/tool-ask-user/README.md create mode 100644 packages/core/tool-ask-user/package.json create mode 100644 packages/core/tool-ask-user/src/index.ts create mode 100644 packages/core/tool-ask-user/tests/tool-ask-user.spec.ts create mode 100644 packages/core/tool-ask-user/tsconfig.json create mode 100644 packages/core/user-interaction/README.md create mode 100644 packages/core/user-interaction/package.json create mode 100644 packages/core/user-interaction/src/index.ts create mode 100644 packages/core/user-interaction/tests/user-interaction.spec.ts create mode 100644 packages/core/user-interaction/tsconfig.json diff --git a/docs/architecture.md b/docs/architecture.md index 216ed949b6..36f8aece28 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -50,6 +50,7 @@ Dependency rule: **extension** plugins depend on interface packages, never on `d | `ctx.sessionPersistence` | `SessionPersistence` (abstract) | dsh-session-persistence | durable persistence seam: create/append/load/list sessions | | `ctx.systemPrompt` | `SystemPrompt` | dsh-system-prompt | ordered sections + tool schemas → `assemble()` | | `ctx.tools` | `ToolRegistry` | dsh-tools | tool definitions; `execute()` through waterfall | +| `ctx.userInteraction` | `UserInteractionService` | dsh-user-interaction | UI-backed human question/answer seam for tools and permission flows | | `ctx.agents` | `AgentRegistry` | dsh-agent | live `Agent` handles + the create/resume factory seam (returns an `AgentHandle` = `{ agent, dispose() }` for owned per-agent teardown) | | `ctx.agentLoop` | `AgentLoop` | dsh-agent-loop | creates `ReactLoopAgent`s and drives their loops | | `ctx.bash` | `BashExecutor` (abstract) | dsh-bash | bash execution seam: foreground runs + background tasks | @@ -198,7 +199,7 @@ Every MVP feature (including the TODO-marked ones), with the mechanism that impl | Built-in tools (Read/Write/Edit/Bash/…) | `ctx.tools.register()`; schemas flow into the assembly automatically. **Bash: implemented** — `dsh-bash` (seam) + `dsh-bash-local` (subprocesses) + `dsh-tool-bash` (`bash`/`bash_output`/`bash_kill`, incl. background tasks) | | ToolSearch / progressive disclosure | wrap `agent/request`, filter `req.tools` | | Tool sandbox (landlock / sandbox-exec) | wrap `tools/execute`, or implement a sandboxing `BashExecutor` (the dsh-bash seam) | -| Permission system / AskUserQuestion | wrap `tools/execute` (veto or ask); register an ask tool | +| Permission system / AskUserQuestion | `dsh-user-interaction` provides `ctx.userInteraction`; `dsh-tool-ask-user` registers `ask_user_question`; permission plugins can also wrap `tools/execute` and ask before delegating | | Plan mode | wrap `tools/execute` (deny writes) + `agent/request` (inject mode prompt) | | Sub-agents (spawn / fork / steer) | TODO seam on `AgentLoop.create()`; fork = seed Session with parent events; `steer()` on the child handle | | MCP | one plugin per server: discover tools → `ctx.tools.register()` | diff --git a/docs/cordis-catalog/events-and-services.md b/docs/cordis-catalog/events-and-services.md index f424b8af09..7d926727a0 100644 --- a/docs/cordis-catalog/events-and-services.md +++ b/docs/cordis-catalog/events-and-services.md @@ -301,7 +301,7 @@ Source: [`packages/core/tools/src/index.ts:43`](../../packages/core/tools/src/in ## Services -The 9 `ctx.` services the harness provides. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against. +The 10 `ctx.` services the harness provides. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against. ### `ctx.agentLoop` — `AgentLoop` @@ -454,6 +454,17 @@ Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../ Source: [`packages/core/tools/src/index.ts:277`](../../packages/core/tools/src/index.ts) +### `ctx.userInteraction` — `UserInteractionService` + +`ctx.userInteraction`: one active UI provider plus an `ask()` surface. + +```ts cordis-catalog +registerProvider(provider: UserInteractionProvider): () => void +async ask(request: AskUserQuestionRequest): Promise +``` + +Source: [`packages/core/user-interaction/src/index.ts:72`](../../packages/core/user-interaction/src/index.ts) + ## Inherited tier (cordis core + loader/hmr/timer) The framework surface every plugin inherits, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the catalog is a complete picture of what `ctx` and the event bus offer, without elevating framework internals to the harness tier's prominence. diff --git a/docs/module-graph.md b/docs/module-graph.md index 93ad58725d..fb21a1184a 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -31,9 +31,7 @@ graph TD tools --> agent tools --> llm tools --> system-prompt - ui-stdio --> agent - ui-stdio --> llm - ui-stdio --> session + user-interaction --> agent acp --> agent acp --> llm acp --> session @@ -48,10 +46,16 @@ graph TD subagent --> agent subagent --> llm subagent --> tools + tool-ask-user --> agent + tool-ask-user --> tools + tool-ask-user --> user-interaction tool-bash --> agent tool-bash --> bash tool-bash --> llm tool-bash --> tools + ui-stdio --> agent + ui-stdio --> session + ui-stdio --> user-interaction agent-core --> agent agent-core --> agent-loop agent-core --> invariants @@ -81,7 +85,9 @@ graph TD stdio-agent --> agent-core stdio-agent --> session stdio-agent --> session-persistence-jsonl + stdio-agent --> tool-ask-user stdio-agent --> ui-stdio + stdio-agent --> user-interaction subagent-fork --> agent subagent-fork --> session subagent-fork --> subagent @@ -107,17 +113,19 @@ graph TD | `session-persistence-jsonl` | `session`, `session-persistence` | | `session-persistence-sqlite` | `session`, `session-persistence` | | `tools` | `agent`, `llm`, `system-prompt` | -| `ui-stdio` | `agent`, `llm`, `session` | +| `user-interaction` | `agent` | | `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools` | | `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` | | `subagent` | `agent`, `llm`, `tools` | +| `tool-ask-user` | `agent`, `tools`, `user-interaction` | | `tool-bash` | `agent`, `bash`, `llm`, `tools` | +| `ui-stdio` | `agent`, `session`, `user-interaction` | | `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` | | `subagent-acp` | `agent`, `llm`, `subagent` | | `subagent-inprocess` | `agent`, `llm`, `session`, `subagent` | | `subagent-mock` | `agent`, `llm`, `subagent` | | `tool-subagent` | `agent`, `llm`, `subagent`, `tools` | | `acp-agent` | `acp`, `agent-core`, `session-persistence-jsonl` | -| `stdio-agent` | `agent`, `agent-core`, `session`, `session-persistence-jsonl`, `ui-stdio` | +| `stdio-agent` | `agent`, `agent-core`, `session`, `session-persistence-jsonl`, `tool-ask-user`, `ui-stdio`, `user-interaction` | | `subagent-fork` | `agent`, `session`, `subagent`, `subagent-inprocess` | | `subagent-spawn` | `subagent`, `subagent-inprocess` | diff --git a/packages/README.md b/packages/README.md index c24e95838f..0fa915f3ef 100644 --- a/packages/README.md +++ b/packages/README.md @@ -28,7 +28,9 @@ dsh-bash ← dsh-brand (abstract executor seam; b dsh-session ← dsh-llm, dsh-brand dsh-system-prompt ← dsh-llm dsh-agent ← dsh-llm, dsh-session, dsh-brand +dsh-user-interaction ← dsh-agent dsh-tools ← dsh-llm, dsh-system-prompt, dsh-agent +dsh-tool-ask-user ← dsh-tools, dsh-user-interaction dsh-bash-local ← dsh-bash (BashExecutor impl) dsh-tool-bash ← dsh-bash, dsh-tools (bash tool schemas) dsh-llm-deepseek ← dsh-llm (DeepSeek adapter) @@ -36,7 +38,7 @@ dsh-llm-pi-ai ← dsh-llm (pi-ai-backed adapter) dsh-agent-loop ← dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent dsh-invariants ← dsh-llm, dsh-session, dsh-agent (dev-mode contract checks) dsh-acp ← dsh-agent, dsh-llm, dsh-session, dsh-session-persistence (ACP JSON-RPC bridge) -dsh-ui-stdio ← dsh-agent, dsh-llm, dsh-session (stdio readline UI plugin) +dsh-ui-stdio ← dsh-agent, dsh-session, dsh-user-interaction (stdio readline UI plugin + user-interaction provider) dsh-llm-replay ← dsh-llm, dsh-session (record/replay adapter for keyless snapshot tests) dsh-subagent ← dsh-agent, dsh-llm, dsh-tools (abstract subagent provider-registry seam) dsh-subagent-mock ← dsh-subagent (scripted provider for tests) @@ -45,7 +47,7 @@ dsh-subagent-fork ← dsh-subagent-spawn, dsh-agent, dsh-session (in-proces dsh-subagent-acp ← dsh-subagent, dsh-agent, dsh-llm, @agentclientprotocol/sdk (out-of-process child over ACP) dsh-tool-subagent ← dsh-subagent, dsh-tools, dsh-agent (model-facing delegation tool) dsh-agent-core ← timer, dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent, dsh-invariants, dsh-tool-bash, dsh-agent-loop (the providerless spine, as one bundle plugin) -dsh-stdio-agent ← dsh-agent-core, dsh-ui-stdio, dsh-session-persistence-jsonl, dsh-agent, dsh-session (stdio chat APP + bin) +dsh-stdio-agent ← dsh-agent-core, dsh-user-interaction, dsh-tool-ask-user, dsh-ui-stdio, dsh-session-persistence-jsonl, dsh-agent, dsh-session (stdio chat APP + bin) dsh-acp-agent ← dsh-agent-core, dsh-acp, dsh-session-persistence-jsonl (ACP server APP + bin) ``` @@ -59,6 +61,8 @@ The rule: **extension** plugins depend on interfaces, never on the concrete loop | `session/` | `core` | Event-sourced session log + in-memory store | `ctx.sessions` | | `system-prompt/` | `core` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` | | `tools/` | `core` | Tool registry + `tools/execute` waterfall | `ctx.tools` | +| `user-interaction/` | `core` | Abstract human question/answer seam | `ctx.userInteraction` | +| `tool-ask-user/` | `core` | Model-facing `ask_user_question` tool | (registers on `ctx.tools`) | | `agent/` | `core` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` | | `agent-loop/` | `core` | THE concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` | | `agent-core/` | `core` | Bundle plugin: the providerless/executor-less/UI-less spine as code (forwards `agent-loop`'s `agents`) | (loads the spine) | diff --git a/packages/core/README.md b/packages/core/README.md index 8d8805471a..8f65eb9ab9 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -7,6 +7,8 @@ The packages every harness build is assembled from: the session log, the system- | `session/` | Event-sourced session log + in-memory store | `ctx.sessions` | | `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` | | `tools/` | Tool registry + `tools/execute` waterfall | `ctx.tools` | +| `user-interaction/` | Human question/answer seam for tools and permission flows | `ctx.userInteraction` | +| `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) | | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` | | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` | | `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) | diff --git a/packages/core/tool-ask-user/README.md b/packages/core/tool-ask-user/README.md new file mode 100644 index 0000000000..dc0b198d04 --- /dev/null +++ b/packages/core/tool-ask-user/README.md @@ -0,0 +1,18 @@ +# @deepseek-ai/dsh-tool-ask-user + +Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the model ask the human a concise question when it needs confirmation, a choice, or missing information before continuing. + +## Tool + +`ask_user_question` accepts: + +- `question` — required question text. +- `header` — optional short heading. +- `options` — optional choices with `label`, `value`, `description`, and `recommended`. +- `allow_custom` — whether free-form answers are allowed; defaults to the provider's normal `true` behavior. + +The tool calls `ctx.userInteraction.ask()` and returns the selected option value or custom answer as a text tool result. + +## Role + +This is the consumer package for the user-interaction seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop. diff --git a/packages/core/tool-ask-user/package.json b/packages/core/tool-ask-user/package.json new file mode 100644 index 0000000000..c1860f48f0 --- /dev/null +++ b/packages/core/tool-ask-user/package.json @@ -0,0 +1,38 @@ +{ + "name": "@deepseek-ai/dsh-tool-ask-user", + "description": "Model-facing ask_user_question tool over the ctx.userInteraction seam", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "@deepseek-ai/dsh-user-interaction": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "@deepseek-ai/dsh-user-interaction": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/core/tool-ask-user/src/index.ts b/packages/core/tool-ask-user/src/index.ts new file mode 100644 index 0000000000..e574db91f3 --- /dev/null +++ b/packages/core/tool-ask-user/src/index.ts @@ -0,0 +1,63 @@ +/** + * Model-facing `ask_user_question` tool over the `ctx.userInteraction` seam. + * The tool pauses until a UI provider returns a human answer, then feeds that + * answer back into the agent loop as an ordinary tool result. + * + * @module @deepseek-ai/dsh-tool-ask-user + */ + +import type { Context } from 'cordis' +import { defineTool } from '@deepseek-ai/dsh-tools' +import type {} from '@deepseek-ai/dsh-user-interaction' + +export const name = 'tool-ask-user' +export const inject = ['tools', 'userInteraction'] + +const description = 'Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. ' + + 'Use options when possible; mark the recommended option when one is safest.' + +export function apply(ctx: Context): void { + ctx.tools.register(defineTool({ + name: 'ask_user_question', + description, + parameters: { + header: { + type: 'string', + description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".', + }, + question: { + type: 'string', + required: true, + description: 'The specific question to ask the user.', + }, + options: { + type: 'array', + description: 'Optional mutually exclusive choices to show the user.', + items: { + type: 'object', + properties: { + label: { type: 'string', required: true, description: 'Short user-facing option label.' }, + value: { type: 'string', description: 'Answer text returned to you if this option is selected. Defaults to label.' }, + description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' }, + recommended: { type: 'boolean', description: 'True for the recommended/default option.' }, + }, + }, + }, + allow_custom: { + type: 'boolean', + description: 'Whether the user may type a free-form answer instead of selecting an option. Defaults to true.', + }, + }, + async execute(args, exec) { + const result = await ctx.userInteraction.ask({ + question: args.question, + ...args.header !== undefined ? { header: args.header } : {}, + ...args.options !== undefined ? { options: args.options } : {}, + ...args.allow_custom !== undefined ? { allowCustom: args.allow_custom } : {}, + ...exec.agent !== undefined ? { agent: exec.agent } : {}, + ...exec.signal !== undefined ? { signal: exec.signal } : {}, + }) + return [{ type: 'text', text: result.answer }] + }, + })) +} diff --git a/packages/core/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/core/tool-ask-user/tests/tool-ask-user.spec.ts new file mode 100644 index 0000000000..ca929533ff --- /dev/null +++ b/packages/core/tool-ask-user/tests/tool-ask-user.spec.ts @@ -0,0 +1,185 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import type { Agent } from '@deepseek-ai/dsh-agent' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import UserInteractionService, { type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-interaction' +import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' + +interface OptionSchemaShape { + properties: { + options: { + items: { + properties: Record + } + } + } +} + +async function setup() { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(UserInteractionService) + await ctx.plugin(toolAskUser) + return ctx +} + +describe('ask_user_question tool', () => { + it('registers a model-facing tool schema', async () => { + const ctx = await setup() + const schema = ctx.tools.schemas().find(tool => tool.name === 'ask_user_question') + + expect(schema).toMatchObject({ + name: 'ask_user_question', + parameters: { + type: 'object', + properties: { + question: { type: 'string' }, + options: { type: 'array' }, + allow_custom: { type: 'boolean' }, + }, + required: ['question'], + }, + }) + const parameters = schema?.parameters as unknown as OptionSchemaShape + expect(parameters.properties.options.items.properties).toMatchObject({ + description: { type: 'string' }, + recommended: { type: 'boolean' }, + }) + expect(parameters.properties.options.items.properties).not.toHaveProperty('desc') + }) + + it('asks the registered user-interaction provider and returns the answer text', async () => { + const ctx = await setup() + const seen: AskUserQuestionRequest[] = [] + ctx.userInteraction.registerProvider({ + async ask(request) { + seen.push(request) + const option = request.options?.[0] + return option === undefined ? { answer: 'Use pnpm' } : { answer: 'Use pnpm', option } + }, + }) + + const result = await ctx.tools.execute({ + callId: CallId('ask-1'), + name: 'ask_user_question', + arguments: { + question: 'Which package manager should I use?', + options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }], + allow_custom: false, + }, + }) + + expect(result).toMatchObject({ + isError: false, + content: [{ type: 'text', text: 'Use pnpm' }], + }) + expect(seen).toMatchObject([{ + question: 'Which package manager should I use?', + options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }], + allowCustom: false, + }]) + }) + + it('passes the tool abort signal to the user-interaction request', async () => { + const ctx = await setup() + const seen: AskUserQuestionRequest[] = [] + ctx.userInteraction.registerProvider({ + async ask(request) { + seen.push(request) + return { answer: 'ok' } + }, + }) + const controller = new AbortController() + + await ctx.tools.execute({ + callId: CallId('ask-2'), + name: 'ask_user_question', + arguments: { question: 'Continue?' }, + signal: controller.signal, + }) + + expect(seen[0]?.signal).toBe(controller.signal) + }) + + it('passes optional header and agent through to the user-interaction request', async () => { + const ctx = await setup() + const seen: AskUserQuestionRequest[] = [] + ctx.userInteraction.registerProvider({ + async ask(request) { + seen.push(request) + return { answer: 'ok' } + }, + }) + const agent = { id: 'main' } as unknown as Agent + + const result = await ctx.tools.execute({ + callId: CallId('ask-3'), + name: 'ask_user_question', + arguments: { header: 'Confirm', question: 'Continue?' }, + agent, + }) + + expect(result.content).toEqual([{ type: 'text', text: 'ok' }]) + expect(seen[0]).toMatchObject({ header: 'Confirm', agent }) + }) + + it('uses an option label when the selected option has no explicit value', async () => { + const ctx = await setup() + ctx.userInteraction.registerProvider({ + async ask(request) { + const option = request.options?.[0] + if (option === undefined) throw new Error('missing option') + return { answer: option.label, option } + }, + }) + + const result = await ctx.tools.execute({ + callId: CallId('ask-4'), + name: 'ask_user_question', + arguments: { + question: 'Pick one', + options: [{ label: 'Fallback label' }], + }, + }) + + expect(result.content).toEqual([{ type: 'text', text: 'Fallback label' }]) + }) + + it('returns the provider-computed answer even when option metadata is present', async () => { + const ctx = await setup() + ctx.userInteraction.registerProvider({ + async ask(request) { + const option = request.options?.[0] + if (option === undefined) throw new Error('missing option') + return { answer: `selected ${option.value}`, option } + }, + }) + + const result = await ctx.tools.execute({ + callId: CallId('ask-5'), + name: 'ask_user_question', + arguments: { + question: 'Pick one', + options: [{ label: 'A', value: 'a' }], + }, + }) + + expect(result.content).toEqual([{ type: 'text', text: 'selected a' }]) + }) + + it('unregisters the tool when its plugin fiber is disposed', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(UserInteractionService) + const fiber = await ctx.plugin(toolAskUser) + expect(ctx.tools.get('ask_user_question')).toBeDefined() + + await fiber.dispose() + + expect(ctx.tools.get('ask_user_question')).toBeUndefined() + }) +}) diff --git a/packages/core/tool-ask-user/tsconfig.json b/packages/core/tool-ask-user/tsconfig.json new file mode 100644 index 0000000000..f51b8c4495 --- /dev/null +++ b/packages/core/tool-ask-user/tsconfig.json @@ -0,0 +1,36 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../agent" + }, + { + "path": "../system-prompt" + }, + { + "path": "../tools" + }, + { + "path": "../user-interaction" + } + ] +} diff --git a/packages/core/user-interaction/README.md b/packages/core/user-interaction/README.md new file mode 100644 index 0000000000..0576495644 --- /dev/null +++ b/packages/core/user-interaction/README.md @@ -0,0 +1,22 @@ +# @deepseek-ai/dsh-user-interaction + +Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a model-facing tool or permission plugin uses when it needs to pause work and ask the human for a decision. + +## Service: `UserInteractionService` (ctx key: `userInteraction`) + +### Public API + +- `ctx.userInteraction.registerProvider(provider): () => void` Register the UI-side provider. Only one provider may be active in a context; disposal unregisters it. +- `ctx.userInteraction.ask(request): Promise` Ask the active provider and wait for the answer. + +### Key Types + +- `AskUserQuestionRequest` — `{ question, header?, options?, allowCustom?, agent?, signal? }`. +- `AskUserQuestionOption` — `{ label, value?, description?, recommended? }`. +- `AskUserQuestionAnswer` — `{ answer, option? }`. +- `UserInteractionProvider` — UI implementation with `ask(request)`. +- `UserInteractionError` — `HarnessError` subclass with codes such as `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`. + +## Role + +This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; UI implementations such as `@deepseek-ai/dsh-ui-stdio` provide the provider. The loop stays unchanged: a tool call simply awaits a promise, and the tool result resumes the normal agent loop. diff --git a/packages/core/user-interaction/package.json b/packages/core/user-interaction/package.json new file mode 100644 index 0000000000..2b96284aca --- /dev/null +++ b/packages/core/user-interaction/package.json @@ -0,0 +1,32 @@ +{ + "name": "@deepseek-ai/dsh-user-interaction", + "description": "Abstract user-interaction seam (ctx.userInteraction) for asking the human during agent runs", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/core/user-interaction/src/index.ts b/packages/core/user-interaction/src/index.ts new file mode 100644 index 0000000000..95c0847e27 --- /dev/null +++ b/packages/core/user-interaction/src/index.ts @@ -0,0 +1,105 @@ +/** + * User-interaction seam (`ctx.userInteraction`): a UI-backed service for + * pausing an agent tool call until the human answers a question. The model- + * facing tool lives in `@deepseek-ai/dsh-tool-ask-user`; UI packages provide + * the single active provider. + * + * @module @deepseek-ai/dsh-user-interaction + */ + +import { Context, Service } from 'cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' + +declare module 'cordis' { + interface Context { + userInteraction: UserInteractionService + } +} + +/** One selectable answer offered to the user. */ +export interface AskUserQuestionOption { + /** User-facing label. */ + label: string + /** Value returned to the model when selected. Defaults to `label`. */ + value?: string + /** Optional extra context rendered by capable UIs. */ + description?: string + /** Marks the recommended/default option. */ + recommended?: boolean +} + +/** Request for a human answer. */ +export interface AskUserQuestionRequest { + /** The question to display. */ + question: string + /** Optional short heading/group label. */ + header?: string + /** Optional choices the UI can render as a menu. */ + options?: AskUserQuestionOption[] + /** Whether free-form answers are accepted. Defaults to `true`. */ + allowCustom?: boolean + /** Calling agent, when the request came from an agent tool call. */ + agent?: Agent + /** Abort signal for the owning tool/step. */ + signal?: AbortSignal +} + +/** The human's answer. */ +export interface AskUserQuestionAnswer { + /** Model-facing answer text. */ + answer: string + /** The selected option, when the answer came from `options`. */ + option?: AskUserQuestionOption +} + +/** UI-side provider for user questions. */ +export interface UserInteractionProvider { + ask(request: AskUserQuestionRequest): Promise +} + +/** Stable error taxonomy for user-interaction failures. */ +export class UserInteractionError extends Error { + readonly code: string + + constructor(message: string, code: string, options?: ErrorOptions) { + super(message, options) + this.code = code + this.name = 'UserInteractionError' + } +} + +/** `ctx.userInteraction`: one active UI provider plus an `ask()` surface. */ +export class UserInteractionService extends Service { + private provider: UserInteractionProvider | undefined + + constructor(ctx: Context) { + super(ctx, 'userInteraction') + } + + /** Register the UI provider. Only one provider may be active in a context. */ + registerProvider(provider: UserInteractionProvider): () => void { + const dispose = this.ctx.effect(function* (this: UserInteractionService) { + if (this.provider !== undefined) { + throw new UserInteractionError('a user-interaction provider is already registered', 'DUPLICATE_PROVIDER') + } + this.provider = provider + yield () => { + this.provider = undefined + } + }.bind(this), 'userInteraction.registerProvider()') + return () => void dispose() + } + + /** Ask the active UI provider and wait for the user's answer. */ + async ask(request: AskUserQuestionRequest): Promise { + if (request.signal?.aborted) { + throw new UserInteractionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED') + } + if (this.provider === undefined) { + throw new UserInteractionError('no user-interaction provider is registered', 'NO_PROVIDER') + } + return this.provider.ask(request) + } +} + +export default UserInteractionService diff --git a/packages/core/user-interaction/tests/user-interaction.spec.ts b/packages/core/user-interaction/tests/user-interaction.spec.ts new file mode 100644 index 0000000000..8b7eefc48c --- /dev/null +++ b/packages/core/user-interaction/tests/user-interaction.spec.ts @@ -0,0 +1,75 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import UserInteractionService, { + UserInteractionError, + type AskUserQuestionRequest, + type UserInteractionProvider, +} from '@deepseek-ai/dsh-user-interaction' + +function provider(answer = 'approved'): UserInteractionProvider & { seen: AskUserQuestionRequest[] } { + const seen: AskUserQuestionRequest[] = [] + return { + seen, + async ask(request) { + seen.push(request) + return { answer } + }, + } +} + +describe('UserInteractionService', () => { + it('delegates ask requests to the registered provider', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = provider('yes') + ctx.userInteraction.registerProvider(p) + + const result = await ctx.userInteraction.ask({ question: 'Proceed?' }) + + expect(result).toEqual({ answer: 'yes' }) + expect(p.seen).toEqual([{ question: 'Proceed?' }]) + }) + + it('rejects ask requests when no provider is registered', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + + await expect(ctx.userInteraction.ask({ question: 'Proceed?' })) + .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_PROVIDER' }) + }) + + it('registers providers with HMR-safe disposal', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = provider() + const dispose = ctx.userInteraction.registerProvider(p) + + dispose() + dispose() + + await expect(ctx.userInteraction.ask({ question: 'Proceed?' })) + .rejects.toMatchObject({ code: 'NO_PROVIDER' }) + }) + + it('rejects duplicate providers instead of replacing the active UI', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + ctx.userInteraction.registerProvider(provider('first')) + + expect(() => ctx.userInteraction.registerProvider(provider('second'))) + .toThrow(UserInteractionError) + }) + + it('fails before reaching the provider when the signal is already aborted', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = { ask: vi.fn(async () => ({ answer: 'too late' })) } + ctx.userInteraction.registerProvider(p) + const controller = new AbortController() + controller.abort() + + await expect(ctx.userInteraction.ask({ question: 'Proceed?', signal: controller.signal })) + .rejects.toMatchObject({ code: 'ASK_ABORTED' }) + expect(p.ask).not.toHaveBeenCalled() + }) +}) diff --git a/packages/core/user-interaction/tsconfig.json b/packages/core/user-interaction/tsconfig.json new file mode 100644 index 0000000000..41720b3057 --- /dev/null +++ b/packages/core/user-interaction/tsconfig.json @@ -0,0 +1,21 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../agent" + } + ] +} diff --git a/packages/support/README.md b/packages/support/README.md index 52f7f6fe25..5358dce364 100644 --- a/packages/support/README.md +++ b/packages/support/README.md @@ -5,7 +5,7 @@ Packages that exist to serve development, testing, and the examples rather than | Package | Role | ctx key | |---|---|---| | `invariants/` | Dev-mode event-contract invariants + session-log freeze | (listens on `session/*`, `agent/*`) | -| `ui-stdio/` | Minimal stdio (readline) UI plugin: renders `agent/*` events, feeds stdin lines to the agent | (drives `ctx.agents`) | +| `ui-stdio/` | Minimal stdio (readline) UI plugin: renders `agent/*` events, feeds stdin lines to the agent, and provides `ctx.userInteraction` answers | (drives `ctx.agents`, registers a user-interaction provider) | | `llm-replay/` | Record/replay adapter: short-circuits `llm/stream` from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) | `invariants` runs only in dev mode (contract checks, not runtime behavior). `ui-stdio` and `llm-replay` were extracted from the examples for reuse and to bring them under the per-file coverage gate; they back the demos and the snapshot test tier. A package graduates OUT of `support/` into a product group only when it gains documented product consumers. diff --git a/packages/support/ui-stdio/README.md b/packages/support/ui-stdio/README.md index b65fd4d8e1..f65452ace5 100644 --- a/packages/support/ui-stdio/README.md +++ b/packages/support/ui-stdio/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-ui-stdio -A minimal stdio (readline) UI, as a plugin. It reads lines from stdin and feeds them to an agent (`send` when idle, `steer` while a turn is running), and renders that agent's streamed output and tool activity to stdout. A UI is "just a plugin" here — it only consumes the `agent/*` event taxonomy plus the `agents` service (`inject: ['agents']`), so the same plugin drives any example or product surface. +A minimal stdio (readline) UI, as a plugin. It reads lines from stdin and feeds them to an agent (`send` when idle, `steer` while a turn is running), renders that agent's streamed output and tool activity to stdout, and provides the `ctx.userInteraction` answer provider for `ask_user_question`. A UI is "just a plugin" here — it consumes the `agent/*` event taxonomy plus the `agents` and `userInteraction` services (`inject: ['agents', 'userInteraction']`), so the same plugin drives any example or product surface with the required seam loaded. This package consolidates what were two near-identical copies under `examples/echo-agent` and `examples/coding-agent`. The coding copy was a superset; this package IS that superset — dimmed chain-of-thought rendering plus robust piped-stdin EOF handling — with the per-consumer differences moved into `Config`. @@ -26,6 +26,10 @@ Rendering is **global** — every agent's events are written to stdout, not just - `agent/turn-start` / `agent/turn-end` — a `[ turn N]` header and a trailing `> ` prompt. - `session/event` — `tool/call` renders `[tool call] name(args)`; `tool/result` renders the joined text blocks as `[tool result] …`. +## User Questions + +When `ctx.userInteraction.ask()` is called, the UI writes the question, renders numbered options when provided, and treats the next stdin line as the answer instead of sending it to the agent. Recommended options render first, option details render from `description`, a numeric line selects the displayed option, an empty line selects the recommended option when one exists, and a non-empty free-form line is accepted when `allowCustom` is not `false`. + ## The I/O seam The production entry point `apply(ctx, config)` binds the real `process` streams. The testable core is `createStdioChat(ctx, config, runtime)`, where `runtime: StdioRuntime` supplies `input` / `output` / `exit`. This seam is deliberately **not** part of the serializable `Config` (streams and functions do not belong in YAML config); it exists so the render, EOF, and disposal branches can be exercised with fakes instead of hijacking globals. diff --git a/packages/support/ui-stdio/package.json b/packages/support/ui-stdio/package.json index 5d65356e79..aa4edbc37e 100644 --- a/packages/support/ui-stdio/package.json +++ b/packages/support/ui-stdio/package.json @@ -23,8 +23,8 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", - "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", + "@deepseek-ai/dsh-user-interaction": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "dependencies": { @@ -34,6 +34,7 @@ "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-user-interaction": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/support/ui-stdio/src/index.ts b/packages/support/ui-stdio/src/index.ts index 070e842094..26a1e37754 100644 --- a/packages/support/ui-stdio/src/index.ts +++ b/packages/support/ui-stdio/src/index.ts @@ -23,9 +23,15 @@ import type { Readable, Writable } from 'node:stream' import type { Context } from 'cordis' import z from 'schemastery' import { AgentId } from '@deepseek-ai/dsh-agent' +import { + UserInteractionError, + type AskUserQuestionAnswer, + type AskUserQuestionOption, + type AskUserQuestionRequest, +} from '@deepseek-ai/dsh-user-interaction' export const name = 'ui-stdio' -export const inject = ['agents'] +export const inject = ['agents', 'userInteraction'] /** Serializable plugin configuration (cordis-native, schemastery). */ export interface Config { @@ -60,6 +66,27 @@ function isTTYPair(input: Readable, output: Writable): boolean { return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY) } +function optionAnswer(option: AskUserQuestionOption): string { + return option.value ?? option.label +} + +function displayOptions(options: AskUserQuestionOption[] = []): AskUserQuestionOption[] { + return options + .map((option, index) => ({ option, index })) + .sort((left, right) => { + if (left.option.recommended === right.option.recommended) return left.index - right.index + return left.option.recommended ? -1 : 1 + }) + .map(({ option }) => option) +} + +interface PendingQuestion { + request: AskUserQuestionRequest + resolve(answer: AskUserQuestionAnswer): void + reject(error: unknown): void + onAbort: () => void +} + /** * The plugin body, parameterized over its I/O runtime. `apply` is the thin * production wrapper that binds the real `process` streams; tests call this @@ -100,6 +127,12 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt output.write('\n> ') }) + ctx.on('agent/error', (agent, turn, step, error) => { + if (inReasoning) output.write('\x1B[0m') + inReasoning = false + output.write(`\n[${agent.id} turn ${turn} step ${step} error] ${error.message}\n> `) + }) + ctx.on('session/event', (_session, event) => { if (event.type === 'tool/call') { const { name: toolName, arguments: args } = event.data @@ -130,6 +163,8 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt let submittedWork = false let sawRunning = false let exitTimer: ReturnType | undefined + let activeQuestion: PendingQuestion | undefined + const questionQueue: PendingQuestion[] = [] const maybeExit = (): void => { if (disposed || !stdinClosed) return @@ -156,7 +191,113 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt if (status === 'idle') maybeExit() }) + const renderQuestion = (pending: PendingQuestion): void => { + const { request } = pending + output.write('\n') + output.write(request.header ? `[${request.header}] ${request.question}\n` : `[question] ${request.question}\n`) + displayOptions(request.options).forEach((option, index) => { + output.write(` ${index + 1}. ${option.label}${option.recommended ? ' (recommended)' : ''}\n`) + if (option.description) output.write(` ${option.description}\n`) + }) + output.write('> ') + } + + const removeAbortListener = (pending: PendingQuestion): void => { + pending.request.signal?.removeEventListener('abort', pending.onAbort) + } + + const startNextQuestion = (): void => { + if (activeQuestion !== undefined) return + const pending = questionQueue.shift() + if (pending === undefined) return + if (pending.request.signal?.aborted) { + pending.reject(new UserInteractionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED')) + startNextQuestion() + return + } + activeQuestion = pending + pending.request.signal?.addEventListener('abort', pending.onAbort, { once: true }) + renderQuestion(pending) + } + + const disposeQuestion = (pending: PendingQuestion): void => { + removeAbortListener(pending) + pending.reject(new UserInteractionError('ask_user_question was interrupted before the user answered', 'ASK_ABORTED')) + } + + const disposePendingQuestions = (): void => { + if (activeQuestion !== undefined) { + disposeQuestion(activeQuestion) + activeQuestion = undefined + } + for (const pending of questionQueue.splice(0)) { + disposeQuestion(pending) + } + } + + const finishQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswer): void => { + removeAbortListener(pending) + activeQuestion = undefined + pending.resolve(answer) + output.write('\n') + startNextQuestion() + } + + const answerQuestion = (line: string): void => { + const pending = activeQuestion as PendingQuestion + + const text = line.trim() + const options = displayOptions(pending.request.options) + const selectedIndex = /^\d+$/.test(text) ? Number(text) - 1 : -1 + const selected = selectedIndex >= 0 ? options[selectedIndex] : undefined + if (selected !== undefined) { + finishQuestion(pending, { answer: optionAnswer(selected), option: selected }) + return + } + + const recommended = options.find(option => option.recommended) + if (text === '' && recommended !== undefined) { + finishQuestion(pending, { answer: optionAnswer(recommended), option: recommended }) + return + } + + const allowCustom = pending.request.allowCustom ?? true + if (allowCustom && text !== '') { + finishQuestion(pending, { answer: text }) + return + } + + output.write(options.length > 0 + ? 'Please enter one of the option numbers' + + (allowCustom ? ' or a custom answer' : '') + + '.\n> ' + : 'Please enter an answer.\n> ') + } + + const disposeUserInteractionProvider = ctx.userInteraction.registerProvider({ + ask(request) { + return new Promise((resolve, reject) => { + const pending: PendingQuestion = { + request, + resolve, + reject, + onAbort: () => { + activeQuestion = undefined + disposeQuestion(pending) + startNextQuestion() + }, + } + questionQueue.push(pending) + startNextQuestion() + }) + }, + }) + reader.on('line', (line) => { + if (activeQuestion !== undefined) { + answerQuestion(line) + return + } const text = line.trim() if (!text) return const agent = ctx.agents.get(agentId) @@ -175,12 +316,15 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt // Fires for BOTH stdin EOF and plugin disposal (reader.close() below); // `disposed` guards teardown so HMR/dispose never exits the process. stdinClosed = true + if (!disposed) disposePendingQuestions() maybeExit() }) output.write(`${welcome}\n> `) return () => { disposed = true if (exitTimer !== undefined) clearTimeout(exitTimer) + disposePendingQuestions() + disposeUserInteractionProvider() disposeStatusListener() reader.close() } diff --git a/packages/support/ui-stdio/tests/readline.spec.ts b/packages/support/ui-stdio/tests/readline.spec.ts index c8b147ddab..2b7e115026 100644 --- a/packages/support/ui-stdio/tests/readline.spec.ts +++ b/packages/support/ui-stdio/tests/readline.spec.ts @@ -16,6 +16,7 @@ function fakeContext(): Context { return { on: vi.fn(() => vi.fn()), effect: vi.fn((callback: () => () => void) => callback()), + userInteraction: { registerProvider: vi.fn(() => vi.fn()) }, } as unknown as Context } diff --git a/packages/support/ui-stdio/tests/ui-stdio.spec.ts b/packages/support/ui-stdio/tests/ui-stdio.spec.ts index bd5e0f7f91..e40847ae51 100644 --- a/packages/support/ui-stdio/tests/ui-stdio.spec.ts +++ b/packages/support/ui-stdio/tests/ui-stdio.spec.ts @@ -5,6 +5,7 @@ import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import AgentRegistry from '@deepseek-ai/dsh-agent' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' import { createStdioChat, type Config, type StdioRuntime } from '../src/index.ts' /** @@ -66,10 +67,11 @@ const CONFIG: Config = { welcome: 'hi there', agent: 'main' } async function setup(config: Config = CONFIG, runtimeOver: Partial = {}) { const ctx = new Context() await ctx.plugin(AgentRegistry) + await ctx.plugin(UserInteractionService) const { runtime, input, out, exit } = makeRuntime(runtimeOver) const fiber = await ctx.plugin(Object.assign((inner: Context) => { createStdioChat(inner, config, runtime) - }, { inject: ['agents'] })) + }, { inject: ['agents', 'userInteraction'] })) return { ctx, fiber, input, out, exit } } @@ -171,9 +173,236 @@ describe('createStdioChat rendering', () => { } as SessionEvent) expect(out.text()).toBe(before) }) + + it('renders agent errors so failed model requests are visible in stdio', async () => { + const { ctx, out } = await setup() + const agent = makeAgent('main') + + ctx.emit('agent/error', agent, 1, 1, new Error('fetch failed')) + + expect(out.text()).toContain('\n[main turn 1 step 1 error] fetch failed\n> ') + }) + + it('resets dim styling when an agent error interrupts reasoning', async () => { + const { ctx, out } = await setup() + const agent = makeAgent('main') + + ctx.emit('agent/stream-chunk', agent, 1, 0, { type: 'reasoning-delta', index: 0, text: 'thinking' }) + ctx.emit('agent/error', agent, 1, 1, new Error('fetch failed')) + + expect(out.text()).toContain('\x1B[2mthinking\x1B[0m\n[main turn 1 step 1 error] fetch failed') + }) }) describe('createStdioChat input', () => { + it('answers a pending user question instead of sending the line to the agent', async () => { + const { ctx, input, out } = await setup() + const agent = makeAgent('main', 'idle') + ctx.agents.register(agent) + + const answer = ctx.userInteraction.ask({ + header: 'Confirm', + question: 'Proceed with the edit?', + options: [{ label: 'Yes', value: 'Proceed', description: 'Apply the edit now.', recommended: true }], + }) + await new Promise(r => setImmediate(r)) + input.feed('Use a smaller change') + + await expect(answer).resolves.toEqual({ answer: 'Use a smaller change' }) + expect(agent.sent).toEqual([]) + expect(out.text()).toContain('[Confirm] Proceed with the edit?') + expect(out.text()).toContain('1. Yes (recommended)') + expect(out.text()).toContain('Apply the edit now.') + }) + + it('answers a pending user question by numeric option selection', async () => { + const { ctx, input } = await setup() + const answer = ctx.userInteraction.ask({ + question: 'Which mode?', + options: [ + { label: 'Safe', value: 'Use safe mode', recommended: true }, + { label: 'Fast', value: 'Use fast mode' }, + ], + allowCustom: false, + }) + await new Promise(r => setImmediate(r)) + input.feed('2') + + await expect(answer).resolves.toEqual({ + answer: 'Use fast mode', + option: { label: 'Fast', value: 'Use fast mode' }, + }) + }) + + it('renders recommended options first and selects by displayed number', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + question: 'Which topic?', + options: [ + { label: 'Hobbies', value: 'hobbies' }, + { label: 'Work', value: 'work', description: 'Questions about current projects.' }, + { label: 'Casual', value: 'casual', recommended: true, description: 'Easy conversation.' }, + ], + allowCustom: false, + }) + await new Promise(r => setImmediate(r)) + + expect(out.text()).toContain([ + '[question] Which topic?', + ' 1. Casual (recommended)', + ' Easy conversation.', + ' 2. Hobbies', + ' 3. Work', + ' Questions about current projects.', + ].join('\n')) + input.feed('1') + + await expect(answer).resolves.toEqual({ + answer: 'casual', + option: { label: 'Casual', value: 'casual', recommended: true, description: 'Easy conversation.' }, + }) + }) + + it('uses the recommended option when the user submits an empty answer', async () => { + const { ctx, input } = await setup() + const answer = ctx.userInteraction.ask({ + question: 'Continue?', + options: [ + { label: 'No' }, + { label: 'Yes', value: 'Continue', recommended: true }, + ], + allowCustom: false, + }) + await new Promise(r => setImmediate(r)) + input.feed('') + + await expect(answer).resolves.toEqual({ + answer: 'Continue', + option: { label: 'Yes', value: 'Continue', recommended: true }, + }) + }) + + it('re-prompts when options are required and the input is invalid', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + question: 'Which mode?', + options: [{ label: 'Safe' }], + allowCustom: false, + }) + await new Promise(r => setImmediate(r)) + input.feed('custom') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('Please enter one of the option numbers.') + input.feed('1') + + await expect(answer).resolves.toEqual({ + answer: 'Safe', + option: { label: 'Safe' }, + }) + }) + + it('re-prompts with custom-answer guidance when options also allow free-form input', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + question: 'Which mode?', + options: [{ label: 'Safe' }], + }) + await new Promise(r => setImmediate(r)) + input.feed('') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.') + input.feed('Use custom mode') + + await expect(answer).resolves.toEqual({ answer: 'Use custom mode' }) + }) + + it('re-prompts when a free-form question receives an empty answer', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ question: 'What should I use?' }) + await new Promise(r => setImmediate(r)) + input.feed('') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('Please enter an answer.') + input.feed('Use defaults') + + await expect(answer).resolves.toEqual({ answer: 'Use defaults' }) + }) + + it('rejects an active question when its signal aborts', async () => { + const { ctx } = await setup() + const controller = new AbortController() + const answer = ctx.userInteraction.ask({ question: 'Continue?', signal: controller.signal }) + const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + await new Promise(r => setImmediate(r)) + + controller.abort() + + await rejected + }) + + it('continues to the next queued question when the active question aborts', async () => { + const { ctx, input, out } = await setup() + const controller = new AbortController() + const first = ctx.userInteraction.ask({ question: 'First?', signal: controller.signal }) + const firstRejected = expect(first).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + const second = ctx.userInteraction.ask({ question: 'Second?' }) + await new Promise(r => setImmediate(r)) + + controller.abort() + await firstRejected + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('[question] Second?') + input.feed('second answer') + + await expect(second).resolves.toEqual({ answer: 'second answer' }) + }) + + it('skips a queued question whose signal aborted before it became active', async () => { + const { ctx, input, out } = await setup() + const controller = new AbortController() + const first = ctx.userInteraction.ask({ question: 'First?' }) + const second = ctx.userInteraction.ask({ question: 'Second?', signal: controller.signal }) + const secondRejected = expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + await new Promise(r => setImmediate(r)) + + controller.abort() + input.feed('first answer') + + await expect(first).resolves.toEqual({ answer: 'first answer' }) + await secondRejected + expect(out.text()).not.toContain('[question] Second?') + }) + + it('rejects active and queued questions when the UI is disposed', async () => { + const { ctx, fiber } = await setup() + const active = ctx.userInteraction.ask({ question: 'Active?' }) + const queued = ctx.userInteraction.ask({ question: 'Queued?' }) + const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + await new Promise(r => setImmediate(r)) + + await fiber.dispose() + + await activeRejected + await queuedRejected + }) + + it('rejects active and queued questions when stdin closes before the user answers', async () => { + const { ctx, input, exit } = await setup() + const active = ctx.userInteraction.ask({ question: 'Active?' }) + const queued = ctx.userInteraction.ask({ question: 'Queued?' }) + const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + await new Promise(r => setImmediate(r)) + + input.finish() + await new Promise(r => setImmediate(r)) + + await activeRejected + await queuedRejected + expect(exit).not.toHaveBeenCalled() + }) + it('sends a typed line to an idle agent', async () => { const { ctx, input } = await setup() const agent = makeAgent('main', 'idle') diff --git a/packages/support/ui-stdio/tsconfig.json b/packages/support/ui-stdio/tsconfig.json index b333de0302..e778da89bf 100644 --- a/packages/support/ui-stdio/tsconfig.json +++ b/packages/support/ui-stdio/tsconfig.json @@ -20,6 +20,9 @@ { "path": "../../core/agent" }, + { + "path": "../../core/user-interaction" + }, { "path": "../../llm/llm" }, diff --git a/packages/ui/stdio-agent/README.md b/packages/ui/stdio-agent/README.md index a78df0fa72..1cde841449 100644 --- a/packages/ui/stdio-agent/README.md +++ b/packages/ui/stdio-agent/README.md @@ -1,5 +1,7 @@ # @deepseek-ai/dsh-stdio-agent +Terminal stdio chat app. It composes the agent-core spine with JSONL persistence, the readline stdio UI, the user-interaction seam, and the `ask_user_question` tool so the demo/coding front door can pause for human confirmation. + The **terminal stdio chat app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`. It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster. @@ -13,7 +15,9 @@ A terminal chat always wants the same cluster, so the package owns it rather tha | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) | | `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model`/`systemPrompt` | | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` | -| `@deepseek-ai/dsh-ui-stdio` | the readline UI, bound to the `main` agent | +| `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools | +| `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool | +| `@deepseek-ai/dsh-ui-stdio` | the readline UI, bound to the `main` agent, and the user-interaction provider | `@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:coding` leaves load it and pass `--expose-internals`. diff --git a/packages/ui/stdio-agent/package.json b/packages/ui/stdio-agent/package.json index bc9c98a411..caf56210cc 100644 --- a/packages/ui/stdio-agent/package.json +++ b/packages/ui/stdio-agent/package.json @@ -37,7 +37,9 @@ "@deepseek-ai/dsh-agent-core": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1", + "@deepseek-ai/dsh-tool-ask-user": "^0.0.1", "@deepseek-ai/dsh-ui-stdio": "^0.0.1", + "@deepseek-ai/dsh-user-interaction": "^0.0.1", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" }, @@ -49,7 +51,9 @@ "@deepseek-ai/dsh-agent-core": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", + "@deepseek-ai/dsh-tool-ask-user": "workspace:^", "@deepseek-ai/dsh-ui-stdio": "workspace:^", + "@deepseek-ai/dsh-user-interaction": "workspace:^", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" } diff --git a/packages/ui/stdio-agent/src/index.ts b/packages/ui/stdio-agent/src/index.ts index c4b9ed202c..efdf55f0a1 100644 --- a/packages/ui/stdio-agent/src/index.ts +++ b/packages/ui/stdio-agent/src/index.ts @@ -41,6 +41,8 @@ import { AgentId } from '@deepseek-ai/dsh-agent' import { SessionId } from '@deepseek-ai/dsh-session' import * as agentCore from '@deepseek-ai/dsh-agent-core' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' +import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' import * as uiStdio from '@deepseek-ai/dsh-ui-stdio' export const name = 'stdio-agent' @@ -94,5 +96,7 @@ export function apply(ctx: Context, config: Config): void { }], }) ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' }) + ctx.plugin(UserInteractionService) + ctx.plugin(toolAskUser) ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.', agent: 'main' }) } diff --git a/packages/ui/stdio-agent/tests/built-bin.e2e.ts b/packages/ui/stdio-agent/tests/built-bin.e2e.ts index 7605b35bb7..d53296929d 100644 --- a/packages/ui/stdio-agent/tests/built-bin.e2e.ts +++ b/packages/ui/stdio-agent/tests/built-bin.e2e.ts @@ -34,7 +34,8 @@ const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js') // to the built `lib/` (package.json `main`), exactly as an installed dep would. const dshPackages = [ 'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt', - 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local', + 'core/tools', 'core/user-interaction', 'core/tool-ask-user', + 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'support/ui-stdio', 'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl', 'ui/stdio-agent', diff --git a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts index f72de0a1da..c21b1c8812 100644 --- a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts +++ b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts @@ -33,6 +33,8 @@ describe('dsh-stdio-agent app', () => { expect(ctx.get('agents')).toBeDefined() expect(ctx.get('agentLoop')).toBeDefined() expect(ctx.get('sessionPersistence')).toBeDefined() + expect(ctx.get('userInteraction')).toBeDefined() + expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined() // The pre-created `main` agent the UI drives. expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined() await ctx.fiber.dispose() diff --git a/packages/ui/stdio-agent/tsconfig.json b/packages/ui/stdio-agent/tsconfig.json index 58b492a549..6cb6130fb7 100644 --- a/packages/ui/stdio-agent/tsconfig.json +++ b/packages/ui/stdio-agent/tsconfig.json @@ -29,6 +29,12 @@ { "path": "../../core/agent-core" }, + { + "path": "../../core/user-interaction" + }, + { + "path": "../../core/tool-ask-user" + }, { "path": "../../session-persistence/session-persistence-jsonl" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 55e565cad2..c6554ad952 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -221,6 +221,27 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/core/tool-ask-user: + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../agent + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../tools + '@deepseek-ai/dsh-user-interaction': + specifier: workspace:^ + version: link:../user-interaction + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/core/tools: devDependencies: '@deepseek-ai/dsh-agent': @@ -236,6 +257,15 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/core/user-interaction: + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../agent + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/llm/llm: devDependencies: '@deepseek-ai/dsh-brand': @@ -578,6 +608,9 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session + '@deepseek-ai/dsh-user-interaction': + specifier: workspace:^ + version: link:../../core/user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -675,9 +708,15 @@ importers: '@deepseek-ai/dsh-session-persistence-jsonl': specifier: workspace:^ version: link:../../session-persistence/session-persistence-jsonl + '@deepseek-ai/dsh-tool-ask-user': + specifier: workspace:^ + version: link:../../core/tool-ask-user '@deepseek-ai/dsh-ui-stdio': specifier: workspace:^ version: link:../../support/ui-stdio + '@deepseek-ai/dsh-user-interaction': + specifier: workspace:^ + version: link:../../core/user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) diff --git a/tsconfig.build.json b/tsconfig.build.json index 4c71d2f14e..bd6073825d 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -18,7 +18,9 @@ { "path": "./packages/session-persistence/session-persistence-sqlite" }, { "path": "./packages/core/system-prompt" }, { "path": "./packages/core/agent" }, + { "path": "./packages/core/user-interaction" }, { "path": "./packages/core/tools" }, + { "path": "./packages/core/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, { "path": "./packages/core/agent-core" }, { "path": "./packages/bash/bash" }, diff --git a/tsconfig.json b/tsconfig.json index dcc23b2fbe..59c69f9684 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -29,7 +29,9 @@ { "path": "./packages/session-persistence/session-persistence-sqlite" }, { "path": "./packages/core/system-prompt" }, { "path": "./packages/core/agent" }, + { "path": "./packages/core/user-interaction" }, { "path": "./packages/core/tools" }, + { "path": "./packages/core/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, { "path": "./packages/core/agent-core" }, { "path": "./packages/bash/bash" }, From 51700d4685898a3ef62512c34f2183b7b532a5b1 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 29 Jun 2026 10:49:07 +0800 Subject: [PATCH 002/119] Fix ask_user_question review findings --- docs/cordis-catalog/events-and-services.md | 2 +- docs/core-data-structures/core.md | 1 + docs/core-data-structures/user-interaction.md | 79 ++++++++ docs/module-graph.md | 10 +- docs/rfc/README.md | 1 + .../feature/2026-06-25-ask-user-question.md | 39 ++++ packages/README.md | 8 +- packages/core/README.md | 1 - packages/core/user-interaction/package.json | 2 + packages/core/user-interaction/src/index.ts | 8 +- packages/core/user-interaction/tsconfig.json | 3 + packages/support/ui-stdio/src/index.ts | 2 +- .../support/ui-stdio/tests/ui-stdio.spec.ts | 13 ++ packages/ui/README.md | 3 + packages/ui/acp-agent/README.md | 4 +- packages/ui/acp-agent/package.json | 4 + packages/ui/acp-agent/src/index.ts | 4 + packages/ui/acp-agent/tests/acp-agent.spec.ts | 2 + packages/ui/acp-agent/tests/built-bin.e2e.ts | 6 +- packages/ui/acp-agent/tsconfig.json | 6 + packages/ui/acp/README.md | 5 +- packages/ui/acp/acp-feature-support.md | 4 +- packages/ui/acp/package.json | 3 + packages/ui/acp/src/index.ts | 156 ++++++++++++++- packages/ui/acp/tests/bridge.spec.ts | 179 +++++++++++++++++- packages/ui/acp/tests/harness.ts | 21 ++ packages/ui/acp/tsconfig.json | 3 + .../ui/stdio-agent/tests/built-bin.e2e.ts | 2 +- packages/ui/stdio-agent/tsconfig.json | 2 +- packages/{core => ui}/tool-ask-user/README.md | 0 .../{core => ui}/tool-ask-user/package.json | 0 .../{core => ui}/tool-ask-user/src/index.ts | 0 .../tool-ask-user/tests/tool-ask-user.spec.ts | 15 ++ .../{core => ui}/tool-ask-user/tsconfig.json | 8 +- pnpm-lock.yaml | 59 +++--- scripts/type-equiv.manifest.json | 6 + tsconfig.build.json | 2 +- tsconfig.json | 2 +- 38 files changed, 611 insertions(+), 54 deletions(-) create mode 100644 docs/core-data-structures/user-interaction.md create mode 100644 docs/rfc/implemented/feature/2026-06-25-ask-user-question.md rename packages/{core => ui}/tool-ask-user/README.md (100%) rename packages/{core => ui}/tool-ask-user/package.json (100%) rename packages/{core => ui}/tool-ask-user/src/index.ts (100%) rename packages/{core => ui}/tool-ask-user/tests/tool-ask-user.spec.ts (93%) rename packages/{core => ui}/tool-ask-user/tsconfig.json (74%) diff --git a/docs/cordis-catalog/events-and-services.md b/docs/cordis-catalog/events-and-services.md index 7d926727a0..8b861e6de1 100644 --- a/docs/cordis-catalog/events-and-services.md +++ b/docs/cordis-catalog/events-and-services.md @@ -463,7 +463,7 @@ registerProvider(provider: UserInteractionProvider): () => void async ask(request: AskUserQuestionRequest): Promise ``` -Source: [`packages/core/user-interaction/src/index.ts:72`](../../packages/core/user-interaction/src/index.ts) +Source: [`packages/core/user-interaction/src/index.ts:70`](../../packages/core/user-interaction/src/index.ts) ## Inherited tier (cordis core + loader/hmr/timer) diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index ad884aeff6..7fd62f38e6 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -19,6 +19,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, the turn-enclosure invariant | | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` | | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/execute` waterfall | +| [user-interaction.md](user-interaction.md) | the human question/answer seam: `AskUserQuestionRequest`/`Answer`, options, provider, structured errors | | [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashTask`s | | [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split | diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md new file mode 100644 index 0000000000..0cf0864121 --- /dev/null +++ b/docs/core-data-structures/user-interaction.md @@ -0,0 +1,79 @@ +# User Interaction + +The user-interaction seam of [dsh-user-interaction](../../packages/core/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-ui-stdio` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations. + +Source: [`packages/core/user-interaction/src/index.ts`](../../packages/core/user-interaction/src/index.ts) + +## Question options + +`AskUserQuestionOption` is the selectable-choice shape. `label` is user-facing, while `value` is the model-facing answer returned when the option is selected; when omitted, providers use the label. + +```ts type-equiv +interface AskUserQuestionOption { + /** User-facing label. */ + label: string + /** Value returned to the model when selected. Defaults to `label`. */ + value?: string + /** Optional extra context rendered by capable UIs. */ + description?: string + /** Marks the recommended/default option. */ + recommended?: boolean +} +``` + +## Ask request + +`AskUserQuestionRequest` is the cross-package request. `options` being absent means free-form input; an optionless request remains free-form even when a caller sets `allowCustom: false`, because there is no selectable option to constrain the answer to. + +```ts type-equiv +interface AskUserQuestionRequest { + /** The question to display. */ + question: string + /** Optional short heading/group label. */ + header?: string + /** Optional choices the UI can render as a menu. */ + options?: AskUserQuestionOption[] + /** Whether free-form answers are accepted. Defaults to `true`. */ + allowCustom?: boolean + /** Calling agent, when the request came from an agent tool call. */ + agent?: Agent + /** Abort signal for the owning tool/step. */ + signal?: AbortSignal +} +``` + +## Answer + +Providers return the model-facing `answer` text and optionally echo the chosen option as metadata. Consumers should use `answer`; the option is for UI/session metadata and diagnostics. + +```ts type-equiv +interface AskUserQuestionAnswer { + /** Model-facing answer text. */ + answer: string + /** The selected option, when the answer came from `options`. */ + option?: AskUserQuestionOption +} +``` + +## Provider + +Only one provider may be active in a context. Provider registration is effect-bound so HMR/disposal removes the active UI. + +```ts type-equiv +interface UserInteractionProvider { + ask(request: AskUserQuestionRequest): Promise +} +``` + +## Errors + +`UserInteractionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `NO_PROVIDER`, `ASK_ABORTED`, or ACP-side cancellation. + +```ts type-equiv +class UserInteractionError extends HarnessError { + constructor(message: string, code: string, options?: ErrorOptions) { + super(message, code, options) + this.name = 'UserInteractionError' + } +} +``` diff --git a/docs/module-graph.md b/docs/module-graph.md index fb21a1184a..5dbf0d2672 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -32,11 +32,13 @@ graph TD tools --> llm tools --> system-prompt user-interaction --> agent + user-interaction --> llm acp --> agent acp --> llm acp --> session acp --> session-persistence acp --> tools + acp --> user-interaction agent-loop --> agent agent-loop --> llm agent-loop --> session @@ -81,6 +83,8 @@ graph TD acp-agent --> acp acp-agent --> agent-core acp-agent --> session-persistence-jsonl + acp-agent --> tool-ask-user + acp-agent --> user-interaction stdio-agent --> agent stdio-agent --> agent-core stdio-agent --> session @@ -113,8 +117,8 @@ graph TD | `session-persistence-jsonl` | `session`, `session-persistence` | | `session-persistence-sqlite` | `session`, `session-persistence` | | `tools` | `agent`, `llm`, `system-prompt` | -| `user-interaction` | `agent` | -| `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools` | +| `user-interaction` | `agent`, `llm` | +| `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools`, `user-interaction` | | `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` | | `subagent` | `agent`, `llm`, `tools` | | `tool-ask-user` | `agent`, `tools`, `user-interaction` | @@ -125,7 +129,7 @@ graph TD | `subagent-inprocess` | `agent`, `llm`, `session`, `subagent` | | `subagent-mock` | `agent`, `llm`, `subagent` | | `tool-subagent` | `agent`, `llm`, `subagent`, `tools` | -| `acp-agent` | `acp`, `agent-core`, `session-persistence-jsonl` | +| `acp-agent` | `acp`, `agent-core`, `session-persistence-jsonl`, `tool-ask-user`, `user-interaction` | | `stdio-agent` | `agent`, `agent-core`, `session`, `session-persistence-jsonl`, `tool-ask-user`, `ui-stdio`, `user-interaction` | | `subagent-fork` | `agent`, `session`, `subagent`, `subagent-inprocess` | | `subagent-spawn` | `subagent`, `subagent-inprocess` | diff --git a/docs/rfc/README.md b/docs/rfc/README.md index 8667cccba2..da55b13bad 100644 --- a/docs/rfc/README.md +++ b/docs/rfc/README.md @@ -84,6 +84,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r | [Rich ACP bash rendering — the terminal card (`_meta`) and command classification](implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) | 2026-06-18 | | [Subagent capability seam](implemented/feature/2026-06-21-subagent-capability-seam.md) | 2026-06-21 | | [ACP subagent backend (out-of-process delegation)](implemented/feature/2026-06-22-acp-subagent-backend.md) | 2026-06-22 | +| [Ask-user question capability](implemented/feature/2026-06-25-ask-user-question.md) | 2026-06-25 | ### Simplification diff --git a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md new file mode 100644 index 0000000000..bc5c140fa5 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md @@ -0,0 +1,39 @@ +# RFC: Ask-user question capability + +Status: implemented + +## Problem + +The agent sometimes cannot proceed safely from model inference alone: it needs the human to choose a path, confirm a risky/default action, or provide missing information. Before this change, the only way to get that answer was for the model to ask in assistant text and then stop, which broke the normal tool-call loop: the agent had no structured way to pause, no option metadata for UIs, no abort/error taxonomy, and no way for non-stdio front doors to present the question consistently. + +This is a user-facing capability, but it also crosses package boundaries. A model-facing tool needs a provider-neutral request vocabulary; each UI surface needs to decide how to show and collect the answer; the agent loop should remain unchanged because a tool call already has the right async shape. + +## Decision + +Introduce `dsh-user-interaction` as the core interface package for `ctx.userInteraction`, and keep the model-facing consumer `dsh-tool-ask-user` under `packages/ui/tool-ask-user` rather than the core spine. The split is intentional: core owns the abstract seam and stable request/answer/error vocabulary; UI product surfaces own the affordance that asks a human and the concrete provider that collects the answer. The tool registers `ask_user_question`, forwards `{ question, header, options, allowCustom, agent, signal }`, and returns the provider-computed `answer` as the tool result. + +The request vocabulary supports a short `header`, the required `question`, optional mutually exclusive `options`, `description` for each option, a `recommended` marker, and `allowCustom`. `label` is user-facing display text; `value` is the model-facing answer for a selected option and defaults to `label`. Providers return `AskUserQuestionAnswer.answer` as the single source of truth; the selected `option` is metadata. The tool schema exposes `description` only, not the synonym `desc`, to keep the model-facing surface small. + +Optionless questions are always free-form, even if a caller passes `allowCustom: false`. The opposite would create an unanswerable prompt: with no option to select and free-form input disallowed, every human answer would be rejected forever. Providers therefore treat "no options" as the free-form shape. + +`UserInteractionError` extends `HarnessError`, so failures such as `NO_PROVIDER`, `ASK_ABORTED`, ACP cancellation, or missing session routing survive `ctx.tools.execute()` as machine-routable `{ name, code }` tool errors. This matches the structured-error taxonomy and lets the model or a wrapping plugin distinguish "user cancelled" from a generic thrown exception. + +## UI mappings + +`dsh-ui-stdio` renders the question in readline, sorts recommended options first, shows each option's `description` on the next line, accepts the recommended option on an empty answer, and rejects pending questions on abort, provider disposal, or stdin EOF. The stdio provider serializes multiple simultaneous questions with an internal queue so only one prompt owns stdin at a time. + +`dsh-acp` provides the same seam for ACP sessions. It routes an ask request from the calling `Agent` through the bridge's `agent→sessionId` reverse map and calls ACP `unstable_createElicitation` with a session-scoped form. Option choices become a `choice` single-select field with the recommended option as the schema default; free-form answers use `answer` for optionless questions and `custom_answer` when options plus custom input are allowed. ACP `decline`/`cancel`, a missing answer, a missing session, and a client without elicitation support all become structured `UserInteractionError`s. + +The ACP mapping deliberately uses elicitation, not `session/request_permission`. `request_permission` is still reserved for the separate permission gate: it is a yes/no-or-policy authorization protocol around tool execution. `ask_user_question` is a general information-gathering tool with optional free-form answers, so ACP form elicitation is the closer protocol fit. The bridge's session routing is shared with the future permission gate, but the user intent is different. + +## Risks / trade-offs + +ACP elicitation is currently marked unstable in the SDK. The fallback is still structured: if a client does not implement it, the tool returns `ASK_FAILED` rather than hanging. A later ACP stabilization may rename or reshape the method; that migration should stay inside `dsh-acp` because the core `ctx.userInteraction` vocabulary is provider-neutral. + +The feature gives the model a powerful pause primitive, so prompt guidance matters. The tool description tells the model to ask concise questions and use options when possible. Product policy can later wrap `tools/execute` to restrict when the tool is allowed, but the loop should not special-case it. + +`dsh-tool-ask-user` lives in `packages/ui` even though it is a tool, because it is a product-facing human-interaction affordance rather than providerless loop infrastructure. The core package remains only the abstract seam; `agent-core` does not load the tool. Front-door app packages such as `stdio-agent` and `acp-agent` opt into it alongside their UI provider. + +## Test plan + +Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, structured tool errors through `ctx.tools.execute()`, option labels/values, and the model schema including the removal of `desc`. `dsh-ui-stdio` tests cover recommended-first display, descriptions, queued questions, EOF/abort cleanup, and optionless free-form input even with `allowCustom: false`. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify both selected-option and optionless free-form elicitation paths continue the agent loop. diff --git a/packages/README.md b/packages/README.md index 0fa915f3ef..3ce54b9996 100644 --- a/packages/README.md +++ b/packages/README.md @@ -28,7 +28,7 @@ dsh-bash ← dsh-brand (abstract executor seam; b dsh-session ← dsh-llm, dsh-brand dsh-system-prompt ← dsh-llm dsh-agent ← dsh-llm, dsh-session, dsh-brand -dsh-user-interaction ← dsh-agent +dsh-user-interaction ← dsh-agent, dsh-llm dsh-tools ← dsh-llm, dsh-system-prompt, dsh-agent dsh-tool-ask-user ← dsh-tools, dsh-user-interaction dsh-bash-local ← dsh-bash (BashExecutor impl) @@ -37,7 +37,7 @@ dsh-llm-deepseek ← dsh-llm (DeepSeek adapter) dsh-llm-pi-ai ← dsh-llm (pi-ai-backed adapter) dsh-agent-loop ← dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent dsh-invariants ← dsh-llm, dsh-session, dsh-agent (dev-mode contract checks) -dsh-acp ← dsh-agent, dsh-llm, dsh-session, dsh-session-persistence (ACP JSON-RPC bridge) +dsh-acp ← dsh-agent, dsh-llm, dsh-session, dsh-session-persistence, dsh-tools, dsh-user-interaction (ACP JSON-RPC bridge + user-interaction provider) dsh-ui-stdio ← dsh-agent, dsh-session, dsh-user-interaction (stdio readline UI plugin + user-interaction provider) dsh-llm-replay ← dsh-llm, dsh-session (record/replay adapter for keyless snapshot tests) dsh-subagent ← dsh-agent, dsh-llm, dsh-tools (abstract subagent provider-registry seam) @@ -48,7 +48,7 @@ dsh-subagent-acp ← dsh-subagent, dsh-agent, dsh-llm, @agentclientprotocol/sdk dsh-tool-subagent ← dsh-subagent, dsh-tools, dsh-agent (model-facing delegation tool) dsh-agent-core ← timer, dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent, dsh-invariants, dsh-tool-bash, dsh-agent-loop (the providerless spine, as one bundle plugin) dsh-stdio-agent ← dsh-agent-core, dsh-user-interaction, dsh-tool-ask-user, dsh-ui-stdio, dsh-session-persistence-jsonl, dsh-agent, dsh-session (stdio chat APP + bin) -dsh-acp-agent ← dsh-agent-core, dsh-acp, dsh-session-persistence-jsonl (ACP server APP + bin) +dsh-acp-agent ← dsh-agent-core, dsh-acp, dsh-user-interaction, dsh-tool-ask-user, dsh-session-persistence-jsonl (ACP server APP + bin) ``` The rule: **extension** plugins depend on interfaces, never on the concrete loop. `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it — swapping the loop means shipping a different bundle, not rewiring every extension. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)). @@ -62,7 +62,6 @@ The rule: **extension** plugins depend on interfaces, never on the concrete loop | `system-prompt/` | `core` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` | | `tools/` | `core` | Tool registry + `tools/execute` waterfall | `ctx.tools` | | `user-interaction/` | `core` | Abstract human question/answer seam | `ctx.userInteraction` | -| `tool-ask-user/` | `core` | Model-facing `ask_user_question` tool | (registers on `ctx.tools`) | | `agent/` | `core` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` | | `agent-loop/` | `core` | THE concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` | | `agent-core/` | `core` | Bundle plugin: the providerless/executor-less/UI-less spine as code (forwards `agent-loop`'s `agents`) | (loads the spine) | @@ -76,6 +75,7 @@ The rule: **extension** plugins depend on interfaces, never on the concrete loop | `session-persistence-sqlite/` | `session-persistence` | SQLite persistence backend | (registers `ctx.sessionPersistence`) | | `invariants/` | `support` | Dev-mode event-contract invariants + session-log freeze | (listens on `session/*`, `agent/*`) | | `acp/` | `ui` | Agent Client Protocol bridge: serves the agent to an ACP editor over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) | +| `tool-ask-user/` | `ui` | Model-facing `ask_user_question` tool | (registers on `ctx.tools`) | | `stdio-agent/` | `ui` | Terminal stdio chat APP: agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) | | `acp-agent/` | `ui` | ACP server APP: agent-core spine + JSONL persistence + the `acp` bridge (no stdout logger), with a `bin` | (composition + `bin`) | | `ui-stdio/` | `support` | Minimal stdio (readline) UI plugin: renders `agent/*` events, feeds stdin lines to the agent | (drives `ctx.agents`) | diff --git a/packages/core/README.md b/packages/core/README.md index 8f65eb9ab9..21e4b3bab0 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -8,7 +8,6 @@ The packages every harness build is assembled from: the session log, the system- | `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` | | `tools/` | Tool registry + `tools/execute` waterfall | `ctx.tools` | | `user-interaction/` | Human question/answer seam for tools and permission flows | `ctx.userInteraction` | -| `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) | | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` | | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` | | `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) | diff --git a/packages/core/user-interaction/package.json b/packages/core/user-interaction/package.json index 2b96284aca..f333195ac7 100644 --- a/packages/core/user-interaction/package.json +++ b/packages/core/user-interaction/package.json @@ -23,10 +23,12 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/core/user-interaction/src/index.ts b/packages/core/user-interaction/src/index.ts index 95c0847e27..ad6c1dde8e 100644 --- a/packages/core/user-interaction/src/index.ts +++ b/packages/core/user-interaction/src/index.ts @@ -9,6 +9,7 @@ import { Context, Service } from 'cordis' import type { Agent } from '@deepseek-ai/dsh-agent' +import { HarnessError } from '@deepseek-ai/dsh-llm' declare module 'cordis' { interface Context { @@ -58,12 +59,9 @@ export interface UserInteractionProvider { } /** Stable error taxonomy for user-interaction failures. */ -export class UserInteractionError extends Error { - readonly code: string - +export class UserInteractionError extends HarnessError { constructor(message: string, code: string, options?: ErrorOptions) { - super(message, options) - this.code = code + super(message, code, options) this.name = 'UserInteractionError' } } diff --git a/packages/core/user-interaction/tsconfig.json b/packages/core/user-interaction/tsconfig.json index 41720b3057..cf9888627c 100644 --- a/packages/core/user-interaction/tsconfig.json +++ b/packages/core/user-interaction/tsconfig.json @@ -16,6 +16,9 @@ }, { "path": "../agent" + }, + { + "path": "../../llm/llm" } ] } diff --git a/packages/support/ui-stdio/src/index.ts b/packages/support/ui-stdio/src/index.ts index 26a1e37754..ddb662719a 100644 --- a/packages/support/ui-stdio/src/index.ts +++ b/packages/support/ui-stdio/src/index.ts @@ -261,7 +261,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt return } - const allowCustom = pending.request.allowCustom ?? true + const allowCustom = options.length === 0 || (pending.request.allowCustom ?? true) if (allowCustom && text !== '') { finishQuestion(pending, { answer: text }) return diff --git a/packages/support/ui-stdio/tests/ui-stdio.spec.ts b/packages/support/ui-stdio/tests/ui-stdio.spec.ts index e40847ae51..cc78b81a98 100644 --- a/packages/support/ui-stdio/tests/ui-stdio.spec.ts +++ b/packages/support/ui-stdio/tests/ui-stdio.spec.ts @@ -328,6 +328,19 @@ describe('createStdioChat input', () => { await expect(answer).resolves.toEqual({ answer: 'Use defaults' }) }) + it('accepts free-form input for an optionless question even when allowCustom is false', async () => { + const { ctx, input } = await setup() + const answer = ctx.userInteraction.ask({ + question: 'Choose?', + allowCustom: false, + }) + await new Promise(r => setImmediate(r)) + + input.feed('Use the default path') + + await expect(answer).resolves.toEqual({ answer: 'Use the default path' }) + }) + it('rejects an active question when its signal aborts', async () => { const { ctx } = await setup() const controller = new AbortController() diff --git a/packages/ui/README.md b/packages/ui/README.md index 075dfd524d..322285c5e4 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -5,9 +5,12 @@ Integrations that expose the agent to an external editor or client. These are ** | Package | Role | ctx key | |---|---|---| | `acp/` | Agent Client Protocol bridge: serves the agent to an ACP editor (Zed) over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) | +| `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) | | `stdio-agent/` | Terminal stdio chat APP: the agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) | | `acp-agent/` | ACP server APP: the agent-core spine + JSONL persistence + the `acp` bridge (no stdout logger), with a `bin` | (composition + `bin`) | A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The readline `ui-stdio` plugin is the unstructured analogue but lives in `support/` because it exists chiefly for the examples and the coverage gate — `ui/` is reserved for surfaces shipped as product. +`tool-ask-user` lives here because it is a model-facing product affordance that depends on a UI/provider seam; it is not part of the providerless core spine. + `stdio-agent` and `acp-agent` are the two **app packages**: each composes the [`core/agent-core`](../core/agent-core/README.md) spine with its coupled front-door cluster (and owns the boot `bin`), so a leaf `cordis.yml` is just the swappable backends plus one app entry. They live in `ui/` because each IS a user-facing front door; the stdout-purity coupling (logger vs. no logger) becomes a property of the artifact rather than a leaf convention. diff --git a/packages/ui/acp-agent/README.md b/packages/ui/acp-agent/README.md index 3403ef2126..fdacbb7f17 100644 --- a/packages/ui/acp-agent/README.md +++ b/packages/ui/acp-agent/README.md @@ -11,8 +11,10 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it | Plugin | Why | |---|---| | `@deepseek-ai/dsh-agent-core` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) | +| `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools | +| `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool | | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) | -| `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC | +| `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers | | ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../acp/README.md)) | | ~~`hmr`~~ | **omitted** — the editor owns the subprocess | diff --git a/packages/ui/acp-agent/package.json b/packages/ui/acp-agent/package.json index 72eb95b2f7..3e732a5441 100644 --- a/packages/ui/acp-agent/package.json +++ b/packages/ui/acp-agent/package.json @@ -35,6 +35,8 @@ "@deepseek-ai/dsh-acp": "^0.0.1", "@deepseek-ai/dsh-agent-core": "^0.0.1", "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1", + "@deepseek-ai/dsh-tool-ask-user": "^0.0.1", + "@deepseek-ai/dsh-user-interaction": "^0.0.1", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" }, @@ -44,6 +46,8 @@ "@deepseek-ai/dsh-acp": "workspace:^", "@deepseek-ai/dsh-agent-core": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", + "@deepseek-ai/dsh-tool-ask-user": "workspace:^", + "@deepseek-ai/dsh-user-interaction": "workspace:^", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" } diff --git a/packages/ui/acp-agent/src/index.ts b/packages/ui/acp-agent/src/index.ts index 625467cac2..c04f2fe72a 100644 --- a/packages/ui/acp-agent/src/index.ts +++ b/packages/ui/acp-agent/src/index.ts @@ -34,6 +34,8 @@ import z from 'schemastery' import * as acp from '@deepseek-ai/dsh-acp' import * as agentCore from '@deepseek-ai/dsh-agent-core' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' +import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' export const name = 'acp-agent' @@ -67,6 +69,8 @@ export const Config: z = z.object({ */ export function apply(ctx: Context, config: Config): void { ctx.plugin(agentCore) + ctx.plugin(UserInteractionService) + ctx.plugin(toolAskUser) ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' }) ctx.plugin(acp, { model: config.model, systemPrompt: config.systemPrompt }) } diff --git a/packages/ui/acp-agent/tests/acp-agent.spec.ts b/packages/ui/acp-agent/tests/acp-agent.spec.ts index 7a02837fca..aa40079cb6 100644 --- a/packages/ui/acp-agent/tests/acp-agent.spec.ts +++ b/packages/ui/acp-agent/tests/acp-agent.spec.ts @@ -29,6 +29,8 @@ describe('dsh-acp-agent composition', () => { expect(ctx.get('sessions')).toBeDefined() expect(ctx.get('sessionPersistence')).toBeDefined() expect(ctx.get('agentLoop')).toBeDefined() + expect(ctx.get('userInteraction')).toBeDefined() + expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined() // No pre-created agents — ACP session/new creates them on demand. expect(ctx.get('agents')!.list()).toHaveLength(0) await ctx.fiber.dispose() diff --git a/packages/ui/acp-agent/tests/built-bin.e2e.ts b/packages/ui/acp-agent/tests/built-bin.e2e.ts index 51c5d53c0b..e2bab79ee4 100644 --- a/packages/ui/acp-agent/tests/built-bin.e2e.ts +++ b/packages/ui/acp-agent/tests/built-bin.e2e.ts @@ -39,10 +39,12 @@ const acpBin = join(repoRoot, 'packages/ui/acp-agent/lib/bin.js') const dshPackages = [ 'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt', - 'core/tools', 'core/agent-loop', 'llm/llm', 'llm/llm-deepseek', 'bash/bash', - 'bash/bash-local', 'bash/tool-bash', 'support/invariants', + 'core/tools', 'core/user-interaction', 'core/agent-loop', 'llm/llm', + 'llm/llm-deepseek', 'bash/bash', 'bash/bash-local', 'bash/tool-bash', + 'support/invariants', 'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl', 'ui/acp', 'ui/acp-agent', + 'ui/tool-ask-user', ] const vendorPackages = [ 'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console', diff --git a/packages/ui/acp-agent/tsconfig.json b/packages/ui/acp-agent/tsconfig.json index ffea8ec6f6..79a68c6337 100644 --- a/packages/ui/acp-agent/tsconfig.json +++ b/packages/ui/acp-agent/tsconfig.json @@ -23,6 +23,12 @@ { "path": "../../core/agent-core" }, + { + "path": "../../core/user-interaction" + }, + { + "path": "../tool-ask-user" + }, { "path": "../../session-persistence/session-persistence-jsonl" } diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md index ad50383542..771cf47af3 100644 --- a/packages/ui/acp/README.md +++ b/packages/ui/acp/README.md @@ -8,7 +8,7 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline ` `apply(ctx, config)` — wires an `AgentSideConnection` (from `@agentclientprotocol/sdk`) to `process.stdin`/`process.stdout` and implements the ACP `Agent` method surface. -`inject: ['agents', 'sessions', 'sessionPersistence', 'tools']` — programs against the interface packages only (never `dsh-agent-loop`). `sessionPersistence` is required because `initialize` advertises `loadSession: true`; `tools` lets a tool own how its calls render (`presentCall`/`presentResult`) — the bridge looks the definition up by name and falls back to a generic presentation when a tool declares none (see Tool-call presentation). +`inject: ['agents', 'sessions', 'sessionPersistence', 'tools', 'userInteraction']` — programs against the interface packages only (never `dsh-agent-loop`). `sessionPersistence` is required because `initialize` advertises `loadSession: true`; `tools` lets a tool own how its calls render (`presentCall`/`presentResult`) — the bridge looks the definition up by name and falls back to a generic presentation when a tool declares none (see Tool-call presentation). `userInteraction` lets the bridge provide ACP-backed answers for tools such as `ask_user_question`. ### Config @@ -29,10 +29,11 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline ` | `session/prompt` | `agent.send()` | supports ACP `text` and `resource_link` blocks; rejects image/audio/embedded resource and empty prompts; one in-flight prompt PER session (independent); settles on the OWNING turn's end (a turn that ends in `error` rejects the RPC) | | `session/cancel` | `agent.cancel()` | the queue-aware cancel: aborts a running step, clears queued + steering work, and drops a turn about to start, then settles the prompt `cancelled` — for ONLY that session (a cancel never touches another session's stream or prompt) | | `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (title/kind/rawInput/content owned by the TOOL via `presentCall`/`presentResult` — see Tool-call presentation) | +| `elicitation/create` | `ctx.userInteraction` provider | `ask_user_question` pauses the tool call and asks the ACP client for a session-scoped form; choices use a `choice` single-select field, free-form answers use `answer`/`custom_answer`, and cancel/decline returns a structured `UserInteractionError` | ## Multi-session -The bridge multiplexes N sessions over one connection. Live sessions are held in a `Map` (forward) with a `WeakMap` reverse map so `agent/*` events — which carry only the `Agent` — demux in O(1). Every `session/event` and `agent/status` is routed strictly to its owning record, so concurrent sessions never cross-settle or interleave their `session/update` notifications. State is per session: one in-flight prompt each, `session/cancel` aborts and settles only its own agent/prompt, and disposal drains every live session in parallel to quiescence. (Per-session *permission* ownership is reserved for the deferred permission gate — `TODO(rfc010-permission-gate)`.) +The bridge multiplexes N sessions over one connection. Live sessions are held in a `Map` (forward) with a `WeakMap` reverse map so `agent/*` events — and `ctx.userInteraction` requests, which carry only the calling `Agent` — demux in O(1). Every `session/event`, `agent/status`, and ask-user elicitation is routed strictly to its owning record, so concurrent sessions never cross-settle or interleave their `session/update` notifications. State is per session: one in-flight prompt each, `session/cancel` aborts and settles only its own agent/prompt, and disposal drains every live session in parallel to quiescence. (Per-session *permission* ownership is reserved for the deferred permission gate — `TODO(rfc010-permission-gate)`.) Background-task isolation rides on `dsh-tool-bash`: bash task ids are global and predictable, so each task carries an opaque owner token — the owning agent's `session.header.id` — stored on the task inside the executor (`dsh-bash`'s `ownerOf(id)` seam). `bash_output`/`bash_kill` reject a task whose token differs from the caller's session token, so one session's agent can't read or kill another's task. Ownership is by session TOKEN, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the token lives on the executor's task it survives a `tool-bash` HMR reload. diff --git a/packages/ui/acp/acp-feature-support.md b/packages/ui/acp/acp-feature-support.md index 429c862b27..56855bfd00 100644 --- a/packages/ui/acp/acp-feature-support.md +++ b/packages/ui/acp/acp-feature-support.md @@ -47,7 +47,7 @@ These are capabilities the bridge would *drive* on the editor. The harness runs | `terminal/wait_for_exit` | S | ❌ | ❌ | ❌ | As above. | | `terminal/kill` | S | ❌ | ❌ | ❌ | As above. | | `terminal/release` | S | ❌ | ❌ | ❌ | As above. | -| `elicitation/create` · `elicitation/complete` | U | ❌ | ✅ | ⚠️ | Structured user-input forms. Claude calls the `unstable_*` elicitation methods (to surface MCP server elicitations); Codex does NOT — its `CodexElicitationHandler` maps elicitations onto `session/request_permission` instead. | +| `elicitation/create` · `elicitation/complete` | U | ⚠️ | ✅ | ⚠️ | The bridge drives `unstable_createElicitation` for `ask_user_question` form prompts (session-scoped, no URL-mode flow yet). Claude calls the `unstable_*` elicitation methods for MCP server elicitations; Codex maps elicitations onto `session/request_permission`. | ## 3. Capabilities @@ -140,7 +140,7 @@ The bridge rejects unsupported prompt blocks rather than silently dropping them Ranked by how commonly the reference adapters ship them and how much UX they unlock: -1. **Permission gate** — `session/request_permission` + permission options. Tracked `TODO(rfc010-permission-gate)`; the reverse map is already wired. Foundational, and a prerequisite for modes. +1. **Permission gate** — `session/request_permission` + permission options. Tracked `TODO(rfc010-permission-gate)`; the reverse map is already wired and shared with `ask_user_question` routing. Foundational, and a prerequisite for modes. 2. **Session lifecycle** — `session/list` + `session/delete` (the persistence layer already lists), then `session/resume` / `session/close`. 3. **Modes / config options / model selection** — coupled to the permission gate. 4. **Agent plan** (`sessionUpdate: 'plan'`) — surface the loop's plan as structured entries. diff --git a/packages/ui/acp/package.json b/packages/ui/acp/package.json index 6973dc5e20..4220f4da52 100644 --- a/packages/ui/acp/package.json +++ b/packages/ui/acp/package.json @@ -32,6 +32,7 @@ "@deepseek-ai/dsh-session": "^0.0.1", "@deepseek-ai/dsh-session-persistence": "^0.0.1", "@deepseek-ai/dsh-tools": "^0.0.1", + "@deepseek-ai/dsh-user-interaction": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "devDependencies": { @@ -45,6 +46,8 @@ "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tool-bash": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", + "@deepseek-ai/dsh-tool-ask-user": "workspace:^", + "@deepseek-ai/dsh-user-interaction": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/ui/acp/src/index.ts b/packages/ui/acp/src/index.ts index ec79e97443..7ab9aeac09 100644 --- a/packages/ui/acp/src/index.ts +++ b/packages/ui/acp/src/index.ts @@ -47,6 +47,9 @@ import { type AuthenticateRequest, type CancelNotification, type ContentBlock as AcpContentBlock, + type CreateElicitationRequest, + type ElicitationContentValue, + type EnumOption, type InitializeRequest, type InitializeResponse, type LoadSessionRequest, @@ -69,6 +72,12 @@ import type { ToolCallKind, ToolCallPresentation, ToolRegistry, ToolResultPresen // Side-effect type import: declaration-merges `ctx.sessionPersistence` onto // Context (the bridge injects it and reads `list()` for load cwd validation). import type {} from '@deepseek-ai/dsh-session-persistence' +import { + UserInteractionError, + type AskUserQuestionAnswer, + type AskUserQuestionOption, + type AskUserQuestionRequest, +} from '@deepseek-ai/dsh-user-interaction' import { acpPromptToText, harnessBlockToAcpContent, @@ -82,7 +91,7 @@ export const name = 'acp' // because `initialize` advertises `loadSession: true`. `tools` lets a tool own // how its calls render (`presentCall`/`presentResult`); the bridge looks up the // definition by name and falls back to a generic presentation when absent. -export const inject = ['agents', 'sessions', 'sessionPersistence', 'tools'] +export const inject = ['agents', 'sessions', 'sessionPersistence', 'tools', 'userInteraction'] /** * Build an ACP "invalid params" error whose human detail rides in the message. @@ -109,6 +118,119 @@ function sameWorkspaceCwd(left: string, right: string): boolean { return resolvePath(left) === resolvePath(right) } +function optionAnswer(option: AskUserQuestionOption): string { + return option.value ?? option.label +} + +function orderedOptions(options: readonly AskUserQuestionOption[] | undefined): AskUserQuestionOption[] { + return [...(options ?? [])].sort((a, b) => Number(Boolean(b.recommended)) - Number(Boolean(a.recommended))) +} + +function optionDescription(option: AskUserQuestionOption): string { + return option.description === undefined + ? option.label + : `${option.label}: ${option.description}` +} + +function selectedOption( + options: readonly AskUserQuestionOption[], + answer: string, +): AskUserQuestionOption | undefined { + return options.find(option => optionAnswer(option) === answer) +} + +function requireStringContent( + content: Record | null | undefined, + key: string, +): string | undefined { + const value = content?.[key] + return typeof value === 'string' && value.trim().length > 0 ? value : undefined +} + +function askAbortError(): UserInteractionError { + return new UserInteractionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED') +} + +function withAbort(promise: Promise, signal: AbortSignal | undefined): Promise { + if (signal === undefined) return promise + if (signal.aborted) return Promise.reject(askAbortError()) + return new Promise((resolve, reject) => { + const onAbort = (): void => { + signal.removeEventListener('abort', onAbort) + reject(askAbortError()) + } + signal.addEventListener('abort', onAbort, { once: true }) + promise.then( + (value) => { + signal.removeEventListener('abort', onAbort) + resolve(value) + }, + (error: unknown) => { + signal.removeEventListener('abort', onAbort) + reject(new Error(String(error), { cause: error })) + }, + ) + }) +} + +function elicitationForQuestion( + sessionId: SessionId, + request: AskUserQuestionRequest, + options: AskUserQuestionOption[], +): CreateElicitationRequest { + const allowCustom = options.length === 0 || (request.allowCustom ?? true) + const title = request.header ?? 'Question' + if (options.length === 0) { + return { + sessionId, + mode: 'form', + message: request.question, + requestedSchema: { + type: 'object', + title, + properties: { + answer: { type: 'string', title: request.question }, + }, + required: ['answer'], + }, + } + } + + const choiceOptions: EnumOption[] = options.map(option => ({ + const: optionAnswer(option), + title: optionDescription(option), + })) + const recommended = options.find(option => option.recommended) + return { + sessionId, + mode: 'form', + message: request.question, + requestedSchema: { + type: 'object', + title, + properties: { + choice: { + type: 'string', + title: request.question, + description: allowCustom ? 'Choose one option, or fill a custom answer below.' : 'Choose one option.', + oneOf: choiceOptions, + ...recommended !== undefined ? { default: optionAnswer(recommended) } : {}, + }, + ...allowCustom + ? { + custom_answer: { + type: 'string' as const, + title: 'Custom answer', + description: 'Optional free-form answer. Leave empty to use the selected option.', + }, + } + : {}, + }, + required: allowCustom ? [] : ['choice'], + }, + } +} + /** Plugin config: the agent template ACP sessions are created from. */ export interface AcpConfig { /** Model name for created agents (must have a registered adapter). */ @@ -224,6 +346,7 @@ export function apply(ctx: Context, config: AcpConfig): void { const sessionPersistence = ctx.sessionPersistence const logger = ctx.logger const tools = ctx.tools + const userInteraction = ctx.userInteraction // A new ToolPresenter per session (and a throwaway per load replay), each given // this warn sink so a throwing tool presenter is logged, not propagated. const makePresenter = (): ToolPresenter => new ToolPresenter(tools, (message) => { logger.warn(message) }) @@ -254,6 +377,37 @@ export function apply(ctx: Context, config: AcpConfig): void { // `notify` never observes it unset — no undefined guard needed. let conn: AgentSideConnection + userInteraction.registerProvider({ + async ask(request: AskUserQuestionRequest): Promise { + if (request.agent === undefined) { + throw new UserInteractionError('ACP user questions must come from an agent-owned request', 'NO_AGENT') + } + const sessionId = bySession.get(request.agent) + if (sessionId === undefined) { + throw new UserInteractionError('ACP user question has no matching session', 'NO_SESSION') + } + const options = orderedOptions(request.options) + const response = await withAbort(conn.unstable_createElicitation( + elicitationForQuestion(sessionId, request, options), + ), request.signal).catch((error: unknown) => { + if (error instanceof UserInteractionError) throw error + throw new UserInteractionError('ACP elicitation request failed', 'ASK_FAILED', { cause: error }) + }) + if (response.action !== 'accept') { + throw new UserInteractionError('ask_user_question was cancelled by the user', 'ASK_CANCELLED') + } + const customAnswer = requireStringContent(response.content, 'custom_answer') + if (customAnswer !== undefined) return { answer: customAnswer } + + const answer = requireStringContent(response.content, options.length === 0 ? 'answer' : 'choice') + if (answer === undefined) { + throw new UserInteractionError('ask_user_question returned no answer', 'NO_ANSWER') + } + const option = selectedOption(options, answer) + return option === undefined ? { answer } : { answer, option } + }, + }) + /** * Reject any RPC after the bridge has torn down. The `AgentSideConnection` * receive loop can outlive the plugin fiber — under an ACP-only HMR reload the diff --git a/packages/ui/acp/tests/bridge.spec.ts b/packages/ui/acp/tests/bridge.spec.ts index e9ebca8d62..602b355b6f 100644 --- a/packages/ui/acp/tests/bridge.spec.ts +++ b/packages/ui/acp/tests/bridge.spec.ts @@ -4,7 +4,7 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk' import { AgentId } from '@deepseek-ai/dsh-agent' -import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts' +import { makeBridgeHarness, textResponse, toolCallResponse, type BridgeHarness } from './harness.ts' /** * End-to-end bridge specs over an in-memory transport: a real @@ -53,6 +53,183 @@ describe('acp bridge', () => { expect(text).toBe('hello there') }) + it('routes ask_user_question through ACP form elicitation and continues with the selected option', async () => { + harness = await makeBridgeHarness({ + storageDir, + withAskUser: true, + script: [ + toolCallResponse('ask-1', 'ask_user_question', { + header: 'Project config', + question: 'Which language should I use?', + options: [ + { label: 'TypeScript', value: 'ts', description: 'Good for UI apps' }, + { label: 'Python', value: 'py', description: 'Good for scripts', recommended: true }, + ], + allow_custom: false, + }), + textResponse('Python it is.'), + ], + }) + harness.onElicitation = () => ({ action: 'accept', content: { choice: 'py' } }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + + const result = await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'ask me' }] }) + + expect(result.stopReason).toBe('end_turn') + expect(harness.elicitationRequests).toHaveLength(1) + expect(harness.elicitationRequests[0]).toMatchObject({ + sessionId, + mode: 'form', + message: 'Which language should I use?', + requestedSchema: { + title: 'Project config', + properties: { + choice: { + default: 'py', + oneOf: [ + { const: 'py', title: 'Python: Good for scripts' }, + { const: 'ts', title: 'TypeScript: Good for UI apps' }, + ], + }, + }, + required: ['choice'], + }, + }) + const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result') + expect(JSON.stringify(toolResult)).toContain('py') + }) + + it('routes optionless ask_user_question through an ACP free-form answer field', async () => { + harness = await makeBridgeHarness({ + storageDir, + withAskUser: true, + script: [ + toolCallResponse('ask-1', 'ask_user_question', { + question: 'What should I name it?', + allow_custom: false, + }), + textResponse('Name recorded.'), + ], + }) + harness.onElicitation = () => ({ action: 'accept', content: { answer: 'apollo' } }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + + await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'ask me' }] }) + + expect(harness.elicitationRequests[0]).toMatchObject({ + requestedSchema: { + properties: { answer: { type: 'string', title: 'What should I name it?' } }, + required: ['answer'], + }, + }) + const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result') + expect(JSON.stringify(toolResult)).toContain('apollo') + }) + + it('supports ACP custom answers alongside choices', async () => { + harness = await makeBridgeHarness({ storageDir, withAskUser: true }) + harness.onElicitation = () => ({ action: 'accept', content: { custom_answer: 'Use Zig' } }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const agent = harness.ctx.agents.get(AgentId(sessionId))! + + const result = await harness.ctx.userInteraction.ask({ + agent, + question: 'Which language?', + options: [{ label: 'TypeScript' }], + }) + + expect(result).toEqual({ answer: 'Use Zig' }) + expect(harness.elicitationRequests[0]).toMatchObject({ + requestedSchema: { + properties: { + choice: { + description: 'Choose one option, or fill a custom answer below.', + oneOf: [{ const: 'TypeScript', title: 'TypeScript' }], + }, + custom_answer: { type: 'string' }, + }, + required: [], + }, + }) + }) + + it('returns raw ACP answers when they do not match a provided option', async () => { + harness = await makeBridgeHarness({ storageDir, withAskUser: true }) + harness.onElicitation = () => ({ action: 'accept', content: { choice: 'something else' } }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const agent = harness.ctx.agents.get(AgentId(sessionId))! + + await expect(harness.ctx.userInteraction.ask({ + agent, + question: 'Pick', + options: [{ label: 'A', value: 'a' }], + allowCustom: false, + })).resolves.toEqual({ answer: 'something else' }) + }) + + it('reports ACP ask-user routing and answer failures as structured errors', async () => { + harness = await makeBridgeHarness({ storageDir, withAskUser: true }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const agent = harness.ctx.agents.get(AgentId(sessionId))! + + await expect(harness.ctx.userInteraction.ask({ question: 'No agent?' })) + .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_AGENT' }) + await expect(harness.ctx.userInteraction.ask({ agent: { id: 'other' } as typeof agent, question: 'No session?' })) + .rejects.toMatchObject({ code: 'NO_SESSION' }) + + harness.onElicitation = () => ({ action: 'cancel' }) + await expect(harness.ctx.userInteraction.ask({ agent, question: 'Cancel?' })) + .rejects.toMatchObject({ code: 'ASK_CANCELLED' }) + + harness.onElicitation = () => ({ action: 'accept', content: {} }) + await expect(harness.ctx.userInteraction.ask({ agent, question: 'Empty?' })) + .rejects.toMatchObject({ code: 'NO_ANSWER' }) + + harness.onElicitation = () => { throw new Error('client boom') } + await expect(harness.ctx.userInteraction.ask({ agent, question: 'Client fails?', signal: new AbortController().signal })) + .rejects.toMatchObject({ code: 'ASK_FAILED' }) + }) + + it('aborts ACP ask-user requests before and while waiting for elicitation', async () => { + harness = await makeBridgeHarness({ storageDir, withAskUser: true }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const agent = harness.ctx.agents.get(AgentId(sessionId))! + + const alreadyAborted = new AbortController() + alreadyAborted.abort() + await expect(harness.ctx.userInteraction.ask({ agent, question: 'Already?', signal: alreadyAborted.signal })) + .rejects.toMatchObject({ code: 'ASK_ABORTED' }) + + let abortedReads = 0 + const racingAbort = { + get aborted() { return abortedReads++ > 0 }, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent() { return false }, + onabort: null, + reason: undefined, + throwIfAborted() {}, + } as AbortSignal + await expect(harness.ctx.userInteraction.ask({ agent, question: 'Raced?', signal: racingAbort })) + .rejects.toMatchObject({ code: 'ASK_ABORTED' }) + + let release: ((value: { action: 'accept'; content: { answer: string } }) => void) | undefined + harness.onElicitation = () => new Promise((resolve) => { release = resolve }) + const pendingAbort = new AbortController() + const ask = harness.ctx.userInteraction.ask({ agent, question: 'Pending?', signal: pendingAbort.signal }) + await new Promise(resolve => setImmediate(resolve)) + pendingAbort.abort() + + await expect(ask).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + release?.({ action: 'accept', content: { answer: 'too late' } }) + }) + it('allows multiple concurrent sessions, each with a distinct id', async () => { harness = await makeBridgeHarness({ storageDir, script: [] }) await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) diff --git a/packages/ui/acp/tests/harness.ts b/packages/ui/acp/tests/harness.ts index 4f6b5ac17a..a49b5c75f9 100644 --- a/packages/ui/acp/tests/harness.ts +++ b/packages/ui/acp/tests/harness.ts @@ -25,11 +25,15 @@ import { ndJsonStream, type Agent as AcpAgent, type Client, + type CreateElicitationRequest, + type CreateElicitationResponse, type RequestPermissionRequest, type RequestPermissionResponse, type SessionNotification, type Stream, } from '@agentclientprotocol/sdk' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' +import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user' import * as AcpPlugin from '../src/index.ts' import { type AcpConfig } from '../src/index.ts' @@ -117,6 +121,10 @@ export interface BridgeHarness { permissionRequests: RequestPermissionRequest[] /** Decide each permission request's outcome (default: cancelled). */ onPermission: (req: RequestPermissionRequest) => RequestPermissionResponse + /** Elicitation requests the bridge issued for ask_user_question. */ + elicitationRequests: CreateElicitationRequest[] + /** Decide each elicitation response (default: cancel). */ + onElicitation: (req: CreateElicitationRequest) => CreateElicitationResponse | Promise /** If set, the client's sessionUpdate throws this (tests notify error path). */ onSessionUpdateError: (() => void) | undefined /** @@ -158,6 +166,8 @@ export async function makeBridgeHarness(options: { * implementation over a mock in tests"). */ withBash?: boolean + /** Plug the REAL `ask_user_question` tool and ACP user-interaction provider. */ + withAskUser?: boolean } = { storageDir: '' }): Promise { const adapter = new MockAdapter(options.script ?? []) @@ -169,6 +179,10 @@ export async function makeBridgeHarness(options: { await ctx.plugin(AgentRegistry) await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SessionPersistenceJsonl, { root: options.storageDir }) + await ctx.plugin(UserInteractionService) + if (options.withAskUser) { + await ctx.plugin(ToolAskUser) + } if (options.withBash) { await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 }) await ctx.plugin(ToolBash) @@ -197,6 +211,7 @@ export async function makeBridgeHarness(options: { const updates: CapturedUpdate[] = [] const sessionUpdates: { sessionId: string; update: CapturedUpdate }[] = [] const permissionRequests: RequestPermissionRequest[] = [] + const elicitationRequests: CreateElicitationRequest[] = [] const harness: BridgeHarness = { ctx, adapter, @@ -204,6 +219,8 @@ export async function makeBridgeHarness(options: { sessionUpdates, permissionRequests, onPermission: () => ({ outcome: { outcome: 'cancelled' } }), + elicitationRequests, + onElicitation: () => ({ action: 'cancel' }), onSessionUpdateError: undefined, client: undefined as unknown as ClientSideConnection, acpFiber: undefined as unknown as BridgeHarness['acpFiber'], @@ -229,6 +246,10 @@ export async function makeBridgeHarness(options: { permissionRequests.push(params) return Promise.resolve(harness.onPermission(params)) }, + unstable_createElicitation(params: CreateElicitationRequest): Promise { + elicitationRequests.push(params) + return Promise.resolve(harness.onElicitation(params)) + }, }) // Wire the bridge (agent side) and the client (test side). The test config diff --git a/packages/ui/acp/tsconfig.json b/packages/ui/acp/tsconfig.json index 5989363d7f..9e24fa0f7a 100644 --- a/packages/ui/acp/tsconfig.json +++ b/packages/ui/acp/tsconfig.json @@ -29,6 +29,9 @@ { "path": "../../core/tools" }, + { + "path": "../../core/user-interaction" + }, { "path": "../../session-persistence/session-persistence" } diff --git a/packages/ui/stdio-agent/tests/built-bin.e2e.ts b/packages/ui/stdio-agent/tests/built-bin.e2e.ts index d53296929d..b28bf382ad 100644 --- a/packages/ui/stdio-agent/tests/built-bin.e2e.ts +++ b/packages/ui/stdio-agent/tests/built-bin.e2e.ts @@ -34,7 +34,7 @@ const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js') // to the built `lib/` (package.json `main`), exactly as an installed dep would. const dshPackages = [ 'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt', - 'core/tools', 'core/user-interaction', 'core/tool-ask-user', + 'core/tools', 'core/user-interaction', 'ui/tool-ask-user', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'support/ui-stdio', 'session-persistence/session-persistence', diff --git a/packages/ui/stdio-agent/tsconfig.json b/packages/ui/stdio-agent/tsconfig.json index 6cb6130fb7..9cd7f8d998 100644 --- a/packages/ui/stdio-agent/tsconfig.json +++ b/packages/ui/stdio-agent/tsconfig.json @@ -33,7 +33,7 @@ "path": "../../core/user-interaction" }, { - "path": "../../core/tool-ask-user" + "path": "../tool-ask-user" }, { "path": "../../session-persistence/session-persistence-jsonl" diff --git a/packages/core/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md similarity index 100% rename from packages/core/tool-ask-user/README.md rename to packages/ui/tool-ask-user/README.md diff --git a/packages/core/tool-ask-user/package.json b/packages/ui/tool-ask-user/package.json similarity index 100% rename from packages/core/tool-ask-user/package.json rename to packages/ui/tool-ask-user/package.json diff --git a/packages/core/tool-ask-user/src/index.ts b/packages/ui/tool-ask-user/src/index.ts similarity index 100% rename from packages/core/tool-ask-user/src/index.ts rename to packages/ui/tool-ask-user/src/index.ts diff --git a/packages/core/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts similarity index 93% rename from packages/core/tool-ask-user/tests/tool-ask-user.spec.ts rename to packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts index ca929533ff..b6fd9d92e4 100644 --- a/packages/core/tool-ask-user/tests/tool-ask-user.spec.ts +++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts @@ -126,6 +126,21 @@ describe('ask_user_question tool', () => { expect(seen[0]).toMatchObject({ header: 'Confirm', agent }) }) + it('returns structured user-interaction errors through tool execution', async () => { + const ctx = await setup() + + const result = await ctx.tools.execute({ + callId: CallId('ask-no-provider'), + name: 'ask_user_question', + arguments: { question: 'Continue?' }, + }) + + expect(result).toMatchObject({ + isError: true, + error: { name: 'UserInteractionError', code: 'NO_PROVIDER' }, + }) + }) + it('uses an option label when the selected option has no explicit value', async () => { const ctx = await setup() ctx.userInteraction.registerProvider({ diff --git a/packages/core/tool-ask-user/tsconfig.json b/packages/ui/tool-ask-user/tsconfig.json similarity index 74% rename from packages/core/tool-ask-user/tsconfig.json rename to packages/ui/tool-ask-user/tsconfig.json index f51b8c4495..06805c0b8f 100644 --- a/packages/core/tool-ask-user/tsconfig.json +++ b/packages/ui/tool-ask-user/tsconfig.json @@ -21,16 +21,16 @@ "path": "../../llm/llm" }, { - "path": "../agent" + "path": "../../core/agent" }, { - "path": "../system-prompt" + "path": "../../core/system-prompt" }, { - "path": "../tools" + "path": "../../core/tools" }, { - "path": "../user-interaction" + "path": "../../core/user-interaction" } ] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c6554ad952..78e26a0864 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -221,27 +221,6 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) - packages/core/tool-ask-user: - devDependencies: - '@deepseek-ai/dsh-agent': - specifier: workspace:^ - version: link:../agent - '@deepseek-ai/dsh-llm': - specifier: workspace:^ - version: link:../../llm/llm - '@deepseek-ai/dsh-system-prompt': - specifier: workspace:^ - version: link:../system-prompt - '@deepseek-ai/dsh-tools': - specifier: workspace:^ - version: link:../tools - '@deepseek-ai/dsh-user-interaction': - specifier: workspace:^ - version: link:../user-interaction - cordis: - specifier: ^4.0.0-rc.6 - version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) - packages/core/tools: devDependencies: '@deepseek-ai/dsh-agent': @@ -262,6 +241,9 @@ importers: '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../agent + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -651,12 +633,18 @@ importers: '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt + '@deepseek-ai/dsh-tool-ask-user': + specifier: workspace:^ + version: link:../tool-ask-user '@deepseek-ai/dsh-tool-bash': specifier: workspace:^ version: link:../../bash/tool-bash '@deepseek-ai/dsh-tools': specifier: workspace:^ version: link:../../core/tools + '@deepseek-ai/dsh-user-interaction': + specifier: workspace:^ + version: link:../../core/user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -678,6 +666,12 @@ importers: '@deepseek-ai/dsh-session-persistence-jsonl': specifier: workspace:^ version: link:../../session-persistence/session-persistence-jsonl + '@deepseek-ai/dsh-tool-ask-user': + specifier: workspace:^ + version: link:../tool-ask-user + '@deepseek-ai/dsh-user-interaction': + specifier: workspace:^ + version: link:../../core/user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) @@ -710,7 +704,7 @@ importers: version: link:../../session-persistence/session-persistence-jsonl '@deepseek-ai/dsh-tool-ask-user': specifier: workspace:^ - version: link:../../core/tool-ask-user + version: link:../tool-ask-user '@deepseek-ai/dsh-ui-stdio': specifier: workspace:^ version: link:../../support/ui-stdio @@ -724,6 +718,27 @@ importers: specifier: ^3.17.0 version: 3.18.0 + packages/ui/tool-ask-user: + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + '@deepseek-ai/dsh-user-interaction': + specifier: workspace:^ + version: link:../../core/user-interaction + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/util/brand: devDependencies: cordis: diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 7872ec8620..c4007ed3eb 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -30,6 +30,12 @@ { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionResult", "source": "packages/core/tools/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" }, diff --git a/tsconfig.build.json b/tsconfig.build.json index bd6073825d..ff9af414a4 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -20,7 +20,7 @@ { "path": "./packages/core/agent" }, { "path": "./packages/core/user-interaction" }, { "path": "./packages/core/tools" }, - { "path": "./packages/core/tool-ask-user" }, + { "path": "./packages/ui/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, { "path": "./packages/core/agent-core" }, { "path": "./packages/bash/bash" }, diff --git a/tsconfig.json b/tsconfig.json index 59c69f9684..9f250e9623 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -31,7 +31,7 @@ { "path": "./packages/core/agent" }, { "path": "./packages/core/user-interaction" }, { "path": "./packages/core/tools" }, - { "path": "./packages/core/tool-ask-user" }, + { "path": "./packages/ui/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, { "path": "./packages/core/agent-core" }, { "path": "./packages/bash/bash" }, From dafb81be7bf6dd2e60374838d61425a251787e42 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 11:35:39 +0800 Subject: [PATCH 003/119] subagent: implement structured output for in-process backends MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seam vocabulary (SubagentStartRequest.outputSchema, SubagentResult .structured) existed but no in-process backend honored it — spawn/fork advertised outputSchema: false. This lands the missing half: - dsh-tools gains a structured-output JSON Schema subset (json-schema.ts): StructuredOutputSchema, assertSupportedOutputSchema (rejects loud outside the enforced subset, every violation listed), validateStructuredValue (path-qualified issues, total). outputSchema's seam type becomes this raw JSON-Schema subset instead of the author-facing SchemaSpec DSL — the schema travels verbatim to the model as a forced tool's parameters. - dsh-subagent-inprocess gains the shared structured runtime: one global structured_output capture tool (placeholder parameters) + a prepend:true agent/request listener doing FINAL-REQUEST enforcement (strip for plain agents, per-run schema for structured children — survives downstream request-replacing listeners) + an agent/turn-continuation veto that stops a child's turn once captured (no wasted extra model step). Lifetime is refcounted by backends (plugin lifetime) AND live runs (start→settle). - startInProcessRun drives the capture: subset asserted before the child exists, instruction appended to the child's system prompt, clean-finish nudge loop (structuredNudgeRetries, backend Config, default 1), captured value on result.structured; a clean finish without a capture settles 'error' (never a silent success with a missing field). - spawn + fork flip outputSchema: true and inject 'tools'. --- docs/cordis-catalog/events.md | 6 +- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/subagent.md | 4 +- docs/module-graph.md | 3 +- packages/core/tools/README.md | 6 + packages/core/tools/src/index.ts | 10 + packages/core/tools/src/json-schema.ts | 322 ++++++++++++++ packages/core/tools/tests/json-schema.spec.ts | 254 +++++++++++ packages/subagent/subagent-fork/README.md | 3 +- packages/subagent/subagent-fork/src/index.ts | 35 +- .../tests/multi-subagent.spec.ts | 4 +- .../subagent-fork/tests/subagent-fork.spec.ts | 16 +- .../subagent/subagent-inprocess/README.md | 21 +- .../subagent/subagent-inprocess/package.json | 1 + .../subagent/subagent-inprocess/src/index.ts | 92 +++- .../subagent-inprocess/src/structured.ts | 193 +++++++++ .../tests/structured.spec.ts | 393 ++++++++++++++++++ .../tests/subagent-inprocess.spec.ts | 6 +- .../subagent/subagent-inprocess/tsconfig.json | 3 + packages/subagent/subagent-spawn/README.md | 5 +- packages/subagent/subagent-spawn/src/index.ts | 48 ++- .../subagent/subagent-spawn/tests/harness.ts | 2 +- .../tests/subagent-spawn.spec.ts | 16 +- packages/subagent/subagent/src/types.ts | 14 +- .../subagent/subagent/tests/service.spec.ts | 4 +- .../subagent-mock/tests/subagent-mock.spec.ts | 4 +- 26 files changed, 1402 insertions(+), 65 deletions(-) create mode 100644 packages/core/tools/src/json-schema.ts create mode 100644 packages/core/tools/tests/json-schema.spec.ts create mode 100644 packages/subagent/subagent-inprocess/src/structured.ts create mode 100644 packages/subagent/subagent-inprocess/tests/structured.spec.ts diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 5fbcecc4eb..c85b459069 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -287,7 +287,7 @@ A tool was registered or unregistered (the available tool set changed). 'tools/change'(): void ``` -Source: [`packages/core/tools/src/index.ts:87`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:97`](../../packages/core/tools/src/index.ts) ### `tools/post-execute` — waterfall @@ -299,7 +299,7 @@ Waterfall AFTER a tool runs — where hook plugins inspect the result and accept Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:82`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:92`](../../packages/core/tools/src/index.ts) ### `tools/pre-execute` — waterfall @@ -311,7 +311,7 @@ Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook pl Types: [ToolExecution](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:66`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:76`](../../packages/core/tools/src/index.ts) ## Inherited events (cordis core + loader/hmr/timer) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 0e1833fd9f..951e182000 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -203,7 +203,7 @@ async execute(exec: ToolExecution): Promise Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:268`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:278`](../../packages/core/tools/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md index 32b5224773..8747f76566 100644 --- a/docs/core-data-structures/subagent.md +++ b/docs/core-data-structures/subagent.md @@ -20,7 +20,7 @@ interface SubagentCapabilities { ## The start request -What a caller asks for when starting a subagent. The tool layer builds this from the model's `{ description, prompt }` plus its own config; the service validates the start-time capabilities against the named provider, then passes it to `provider.start`. `parent` is REQUIRED — in-process backends read `parent.session.header` for the working directory, the `parentSession` lineage, and the delegation depth. The three optional fields (`outputSchema`, `maxDepth`, `toolFilter`) each gate on the matching `SubagentCapabilities` flag. +What a caller asks for when starting a subagent. The tool layer builds this from the model's `{ description, prompt }` plus its own config; the service validates the start-time capabilities against the named provider, then passes it to `provider.start`. `parent` is REQUIRED — in-process backends read `parent.session.header` for the working directory, the `parentSession` lineage, and the delegation depth. The three optional fields (`outputSchema`, `maxDepth`, `toolFilter`) each gate on the matching `SubagentCapabilities` flag. `outputSchema` is an object-rooted JSON Schema within the subset `assertSupportedOutputSchema` (dsh-tools) enforces — a schema outside it is rejected loud at start; the in-process backends realize it with a forced `structured_output` capture tool (see the [driver README](../../packages/subagent/subagent-inprocess/README.md)). ```ts type-equiv interface SubagentStartRequest { @@ -28,7 +28,7 @@ interface SubagentStartRequest { parent: Agent signal?: AbortSignal agentOptions?: AgentOptions - outputSchema?: SchemaSpec + outputSchema?: StructuredOutputSchema maxDepth?: number toolFilter?: { allow?: string[]; deny?: string[] } } diff --git a/docs/module-graph.md b/docs/module-graph.md index 50ef532fa4..e8f1edfaa5 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -104,6 +104,7 @@ graph TD subagent-inprocess --> llm subagent-inprocess --> session subagent-inprocess --> subagent + subagent-inprocess --> tools subagent-mock --> agent subagent-mock --> llm subagent-mock --> subagent @@ -169,7 +170,7 @@ graph TD | `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` | | `hooks-claude` | `agent`, `hook-protocol`, `llm`, `session`, `subagent`, `tools` | | `subagent-acp` | `agent`, `llm`, `subagent` | -| `subagent-inprocess` | `agent`, `llm`, `session`, `subagent` | +| `subagent-inprocess` | `agent`, `llm`, `session`, `subagent`, `tools` | | `subagent-mock` | `agent`, `llm`, `subagent` | | `tool-subagent` | `agent`, `llm`, `subagent`, `tools` | | `acp-agent` | `acp`, `agent-core`, `app-boot`, `session-persistence-jsonl` | diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 65039aea58..d43f24e123 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -71,6 +71,12 @@ A `defineTool` tool also **validates the model-generated arguments against its ` See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details. +### Structured-output schema subset + +A separate vocabulary for callers that DEMAND a machine-readable value from an agent — the subagent seam's `SubagentStartRequest.outputSchema` (and, by extension, a workflow's `agent({ schema })`). Unlike `SchemaSpec` (the author-facing DSL for tool parameters), a `StructuredOutputSchema` is an object-rooted **raw JSON Schema subset** as data: it travels verbatim to the model as a forced tool's `parameters`, and the produced value is validated against it. + +The subset is deliberately narrow and REJECTS LOUD outside it — accepting a keyword the validator doesn't enforce would validate less than the schema promises (accepted-then-ignored). Supported: single-string `type` (`object`/`array`/`string`/`number`/`integer`/`boolean`/`null`; type arrays rejected), `properties`/`required`/`additionalProperties` (boolean; every `required` key must be declared), `items`, scalar-only `enum`/`const`; annotations (`description`/`title`/`default`/`examples`) are ignored but must still be JSON data. `assertSupportedOutputSchema(schema)` throws `OutputSchemaError` (`code: 'UNSUPPORTED_SCHEMA'`, listing every violation) for anything else; `validateStructuredValue(schema, value)` returns path-qualified violations (empty = valid, total — never throws). + ### Tool-owned UI presentation A tool owns how ITS calls render in a UI (an editor's tool-call card, a CLI log line) — a UI plugin must NOT special-case tool names. A `ToolDefinition` may declare two optional, pure, display-only methods that return a **`card`-tagged render intent** (a discriminated union — a tool declares its card kind once and a UI bridge switches on `card`): diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index dd0ed918db..39dafd6f1a 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -28,6 +28,16 @@ export { type JsonSchemaObject, } from './schema.ts' +export { + assertSupportedOutputSchema, + validateStructuredValue, + OutputSchemaError, + type StructuredOutputSchema, + type StructuredSchemaNode, + type StructuredSchemaType, + type StructuredScalar, +} from './json-schema.ts' + // The render-intent vocabulary a tool declares via `presentCall`/`presentResult` // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools` // stays the single public surface for consumers (producers + the ACP bridge). diff --git a/packages/core/tools/src/json-schema.ts b/packages/core/tools/src/json-schema.ts new file mode 100644 index 0000000000..35eeb240a4 --- /dev/null +++ b/packages/core/tools/src/json-schema.ts @@ -0,0 +1,322 @@ +/** + * Structured-output JSON Schema subset: the vocabulary a caller uses to demand + * a machine-readable result from a subagent (`SubagentStartRequest.outputSchema`) + * or a workflow `agent()` call. + * + * This is deliberately NOT full JSON Schema. The schema travels verbatim to the + * model as a forced tool's `parameters`, and the value the model produces is + * validated here — so every accepted keyword must be one this module actually + * enforces. Accepting a keyword we don't enforce would validate less than the + * schema promises (accepted-then-ignored), so anything outside the subset is + * REJECTED LOUD by {@link assertSupportedOutputSchema} instead. The subset: + * + * - `type` — a single string (`object`/`array`/`string`/`number`/`integer`/ + * `boolean`/`null`); type ARRAYS (`["string","null"]`) are rejected. + * - `properties`/`required`/`additionalProperties` (boolean) on objects; every + * `required` key must be declared in `properties`. `additionalProperties` + * absent keeps standard JSON Schema semantics (extra keys allowed). + * - `items` on arrays (absent ⇒ any JSON items). + * - `enum` (non-empty, scalars only) and `const` (scalar) on scalar types. + * - Annotations `description`/`title`/`default`/`examples` are allowed and + * ignored (they constrain nothing), except that they must still be JSON data + * — the schema is serialized onto the wire, so a non-JSON annotation would be + * silently mangled. + * + * Values checked by {@link validateStructuredValue} are expected to be plain + * host-realm JSON data (model tool-call arguments are parsed wire JSON; a + * caller holding foreign-realm data materializes it first). + * + * @module dsh-tools/json-schema + */ + +import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm' + +/** The scalar values `enum`/`const` may carry (finite numbers only). */ +export type StructuredScalar = string | number | boolean | null + +/** The `type` keywords the subset accepts. */ +export type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null' + +/** + * One node of the structured-output schema subset. Recursive via `properties` + * and `items`; see the module doc for the exact keyword semantics. + */ +export interface StructuredSchemaNode { + type: StructuredSchemaType + /** Nested property schemas (`type: 'object'` only). */ + properties?: Record + /** Required property names; each must appear in `properties`. */ + required?: string[] + /** `false` rejects undeclared keys; absent/`true` allows them (JSON Schema default). */ + additionalProperties?: boolean + /** Item schema (`type: 'array'` only); absent ⇒ any JSON items. */ + items?: StructuredSchemaNode + /** Allowed values (scalar types only). */ + enum?: StructuredScalar[] + /** The single allowed value (scalar types only). */ + const?: StructuredScalar + /** Annotation, ignored for validation. */ + description?: string + /** Annotation, ignored for validation. */ + title?: string + /** Annotation, ignored for validation (must still be JSON data). */ + default?: unknown + /** Annotation, ignored for validation (must still be JSON data). */ + examples?: unknown +} + +/** A structured-output schema: an OBJECT-rooted {@link StructuredSchemaNode}. */ +export type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' } + +/** + * Thrown by {@link assertSupportedOutputSchema} when a schema falls outside the + * supported subset. Extends {@link HarnessError} (`code: 'UNSUPPORTED_SCHEMA'`) + * so seam code and tool results can route on it; `violations` lists every + * offending path, not just the first. + */ +export class OutputSchemaError extends HarnessError { + /** The individual violation messages, in walk order. */ + readonly violations: string[] + + constructor(violations: string[]) { + super(`unsupported output schema: ${violations.join('; ')}`, 'UNSUPPORTED_SCHEMA') + this.name = 'OutputSchemaError' + this.violations = violations + } +} + +/** The keywords the subset accepts, checked (`constraint`) or ignored (`annotation`). */ +const CONSTRAINT_KEYWORDS = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const']) +const ANNOTATION_KEYWORDS = new Set(['description', 'title', 'default', 'examples']) + +const SCHEMA_TYPES: readonly StructuredSchemaType[] = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'] + +/** Whether a value is a non-null, non-array object (structural, realm-agnostic). */ +function isObjectLike(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** Whether a value is a supported scalar (`enum`/`const` member): string, finite number, boolean, or null. */ +function isStructuredScalar(value: unknown): value is StructuredScalar { + return value === null || typeof value === 'string' || typeof value === 'boolean' + || (typeof value === 'number' && Number.isFinite(value)) +} + +/** + * Whether a value is JSON data (annotation payloads only): scalars, arrays, and + * object-likes of such values. Realm-agnostic on purpose (no prototype check) — + * the schema may have been materialized from another realm; structural JSON-ness + * is what the wire needs. Cycles are rejected via `seen`. + */ +function isJsonData(value: unknown, seen: Set): boolean { + if (isStructuredScalar(value)) return true + // The scalar check above already returned for null, so `object` here is a real object. + if (typeof value !== 'object') return false + if (seen.has(value)) return false + seen.add(value) + try { + if (Array.isArray(value)) return value.every(entry => isJsonData(entry, seen)) + return Object.values(value).every(entry => isJsonData(entry, seen)) + } finally { + seen.delete(value) + } +} + +/** Collect subset violations for one schema node (recursive walk). */ +function checkSchemaNode(node: unknown, path: string, violations: string[], seen: Set): void { + if (!isObjectLike(node)) { + violations.push(`${path} must be a schema object`) + return + } + if (seen.has(node)) { + violations.push(`${path} is circular`) + return + } + seen.add(node) + + for (const key of Object.keys(node)) { + if (CONSTRAINT_KEYWORDS.has(key)) continue + if (ANNOTATION_KEYWORDS.has(key)) { + if (!isJsonData(node[key], new Set())) violations.push(`${path}.${key} annotation must be JSON data`) + continue + } + violations.push(`${path}.${key} is not a supported keyword (subset: type/properties/required/additionalProperties/items/enum/const + annotations)`) + } + if (typeof node.description !== 'undefined' && typeof node.description !== 'string') { + violations.push(`${path}.description must be a string`) + } + if (typeof node.title !== 'undefined' && typeof node.title !== 'string') { + violations.push(`${path}.title must be a string`) + } + + const type = node.type + if (typeof type !== 'string' || !(SCHEMA_TYPES as readonly unknown[]).includes(type)) { + violations.push(Array.isArray(type) + ? `${path}.type must be a single type string (type arrays are not supported)` + : `${path}.type must be one of ${SCHEMA_TYPES.join('/')}`) + seen.delete(node) + return + } + const schemaType = type as StructuredSchemaType + + // Keywords that only make sense on one type are rejected elsewhere — an + // `items` on an object (or `properties` on a string) is a schema-author bug + // the subset surfaces rather than ignores. + const allowedFor: Record = { + properties: ['object'], + required: ['object'], + additionalProperties: ['object'], + items: ['array'], + enum: ['string', 'number', 'integer', 'boolean', 'null'], + const: ['string', 'number', 'integer', 'boolean', 'null'], + } + for (const [key, types] of Object.entries(allowedFor)) { + if (key in node && !types.includes(schemaType)) { + violations.push(`${path}.${key} is not supported on type "${schemaType}"`) + } + } + + switch (schemaType) { + case 'object': { + const properties = node.properties + if (properties !== undefined) { + if (!isObjectLike(properties)) { + violations.push(`${path}.properties must be an object of schemas`) + } else { + for (const [key, child] of Object.entries(properties)) { + checkSchemaNode(child, `${path}.properties.${key}`, violations, seen) + } + } + } + const required = node.required + if (required !== undefined) { + if (!Array.isArray(required) || required.some(entry => typeof entry !== 'string')) { + violations.push(`${path}.required must be an array of strings`) + } else { + const declared = isObjectLike(properties) ? properties : {} + for (const key of required) { + if (!(key in declared)) violations.push(`${path}.required names "${key}" which is not in properties`) + } + } + } + if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean') { + violations.push(`${path}.additionalProperties must be a boolean`) + } + break + } + case 'array': { + if (node.items !== undefined) checkSchemaNode(node.items, `${path}.items`, violations, seen) + break + } + case 'string': + case 'number': + case 'integer': + case 'boolean': + case 'null': { + const allowed = node.enum + if (allowed !== undefined) { + if (!Array.isArray(allowed) || allowed.length === 0 || !allowed.every(entry => isStructuredScalar(entry))) { + violations.push(`${path}.enum must be a non-empty array of scalars`) + } + } + if ('const' in node && !isStructuredScalar(node.const)) { + violations.push(`${path}.const must be a scalar`) + } + break + } + /* v8 ignore start -- defensive: schemaType was membership-checked against SCHEMA_TYPES above, so no runtime value reaches here */ + default: + assertNever(schemaType, 'assertSupportedOutputSchema') + /* v8 ignore stop */ + } + + seen.delete(node) +} + +/** + * Assert `schema` is a supported {@link StructuredOutputSchema} — object-rooted + * and entirely within the enforced subset. Throws {@link OutputSchemaError} + * (`UNSUPPORTED_SCHEMA`) listing EVERY violation; returns (and narrows) on + * success. Call this at the seam boundary, before any child is created. + * @param schema - the caller-supplied schema (unknown until asserted). + */ +export function assertSupportedOutputSchema(schema: unknown): asserts schema is StructuredOutputSchema { + const violations: string[] = [] + checkSchemaNode(schema, 'schema', violations, new Set()) + if (violations.length === 0 && (schema as StructuredSchemaNode).type !== 'object') { + violations.push('schema.type must be "object" (structured output is object-rooted)') + } + if (violations.length > 0) throw new OutputSchemaError(violations) +} + +/** Collect violations for one value against an (already asserted) schema node. */ +function checkValue(node: StructuredSchemaNode, value: unknown, path: string): string[] { + switch (node.type) { + case 'object': { + if (!isObjectLike(value)) return [`"${path}" must be an object`] + const violations: string[] = [] + const properties = node.properties ?? {} + for (const key of node.required ?? []) { + if (value[key] === undefined) violations.push(`missing required property "${path}.${key}"`) + } + for (const [key, child] of Object.entries(properties)) { + if (value[key] === undefined) continue + violations.push(...checkValue(child, value[key], `${path}.${key}`)) + } + if (node.additionalProperties === false) { + for (const key of Object.keys(value)) { + if (!(key in properties)) violations.push(`"${path}.${key}" is not a declared property (additionalProperties: false)`) + } + } + return violations + } + case 'array': { + if (!Array.isArray(value)) return [`"${path}" must be an array`] + if (!node.items) return [] + const items = node.items + return value.flatMap((entry, index) => checkValue(items, entry, `${path}[${index}]`)) + } + case 'string': { + if (typeof value !== 'string') return [`"${path}" must be a string`] + break + } + case 'number': { + if (typeof value !== 'number' || !Number.isFinite(value)) return [`"${path}" must be a finite number`] + break + } + case 'integer': { + if (typeof value !== 'number' || !Number.isInteger(value)) return [`"${path}" must be an integer`] + break + } + case 'boolean': { + if (typeof value !== 'boolean') return [`"${path}" must be a boolean`] + break + } + case 'null': { + if (value !== null) return [`"${path}" must be null`] + break + } + default: + return assertNever(node.type, 'validateStructuredValue') + } + // Scalar constraint checks, shared by every scalar branch above. + if (node.enum && !node.enum.includes(value)) { + return [`"${path}" must be one of ${JSON.stringify(node.enum)}`] + } + if ('const' in node && value !== node.const) { + return [`"${path}" must be ${JSON.stringify(node.const)}`] + } + return [] +} + +/** + * Validate a value against an (already {@link assertSupportedOutputSchema}- + * asserted) schema. Returns human-readable, path-qualified violation messages + * — empty means valid. Total: never throws, however malformed the value. + * @param schema - the asserted schema to check against. + * @param value - the candidate value (e.g. parsed tool-call arguments). + * @returns every violation found, in walk order (empty = valid). + */ +export function validateStructuredValue(schema: StructuredOutputSchema, value: unknown): string[] { + return checkValue(schema, value, 'value') +} diff --git a/packages/core/tools/tests/json-schema.spec.ts b/packages/core/tools/tests/json-schema.spec.ts new file mode 100644 index 0000000000..e7635b06f3 --- /dev/null +++ b/packages/core/tools/tests/json-schema.spec.ts @@ -0,0 +1,254 @@ +import { describe, expect, it } from 'vitest' +import { + assertSupportedOutputSchema, + OutputSchemaError, + validateStructuredValue, + type StructuredOutputSchema, +} from '../src/json-schema.ts' + +/** Assert-and-narrow helper: the asserted schema, typed. */ +function asserted(schema: unknown): StructuredOutputSchema { + assertSupportedOutputSchema(schema) + return schema +} + +/** The violations OutputSchemaError carries for a bad schema (throws if it passes). */ +function violationsOf(schema: unknown): string[] { + try { + assertSupportedOutputSchema(schema) + } catch (error: unknown) { + if (error instanceof OutputSchemaError) return error.violations + throw error + } + throw new Error('expected the schema to be rejected') +} + +describe('assertSupportedOutputSchema', () => { + it('accepts a representative subset schema (all supported keywords)', () => { + const schema = asserted({ + type: 'object', + description: 'a finding', + title: 'Finding', + properties: { + file: { type: 'string', description: 'path' }, + line: { type: 'integer' }, + severity: { type: 'string', enum: ['low', 'high'] }, + kind: { type: 'string', const: 'bug' }, + score: { type: 'number' }, + confirmed: { type: 'boolean' }, + parent: { type: 'null' }, + tags: { type: 'array', items: { type: 'string' } }, + nested: { + type: 'object', + properties: { x: { type: 'number', default: 3, examples: [1, 2] } }, + additionalProperties: false, + }, + anything: { type: 'array' }, + }, + required: ['file', 'line'], + additionalProperties: true, + }) + expect(schema.type).toBe('object') + }) + + it('rejects a non-object root (scalar/array-rooted schemas)', () => { + expect(violationsOf({ type: 'string' })).toEqual(['schema.type must be "object" (structured output is object-rooted)']) + expect(violationsOf({ type: 'array', items: { type: 'string' } })) + .toContain('schema.type must be "object" (structured output is object-rooted)') + }) + + it('rejects non-object schema nodes and missing/unknown type', () => { + expect(violationsOf('nope')).toEqual(['schema must be a schema object']) + expect(violationsOf(null)).toEqual(['schema must be a schema object']) + expect(violationsOf([])).toEqual(['schema must be a schema object']) + expect(violationsOf({})).toEqual(['schema.type must be one of object/array/string/number/integer/boolean/null']) + expect(violationsOf({ type: 'tuple' })[0]).toMatch(/type must be one of/) + expect(violationsOf({ type: 'object', properties: { a: 'str' } })).toEqual(['schema.properties.a must be a schema object']) + }) + + it('rejects type ARRAYS with a dedicated message', () => { + expect(violationsOf({ type: ['string', 'null'] })) + .toEqual(['schema.type must be a single type string (type arrays are not supported)']) + }) + + it('rejects unsupported constraint keywords loudly (never accepted-then-ignored)', () => { + for (const keyword of ['oneOf', 'anyOf', 'allOf', 'not', 'pattern', 'minimum', 'maxLength', '$ref']) { + const bad = violationsOf({ type: 'object', [keyword]: [] }) + expect(bad.some(v => v.includes(`schema.${keyword} is not a supported keyword`))).toBe(true) + } + }) + + it('reports EVERY violation, not just the first', () => { + const bad = violationsOf({ + type: 'object', + pattern: 'x', + properties: { a: { type: 'weird' }, b: { type: 'string', minimum: 1 } }, + }) + expect(bad.length).toBe(3) + }) + + it('rejects keywords on the wrong type (items on object, properties on string, enum on object)', () => { + expect(violationsOf({ type: 'object', items: { type: 'string' } })) + .toEqual(['schema.items is not supported on type "object"']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'string', properties: {} } } })) + .toEqual(['schema.properties.a.properties is not supported on type "string"']) + expect(violationsOf({ type: 'object', enum: [1] })) + .toEqual(['schema.enum is not supported on type "object"']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'array', const: 1 } } })) + .toEqual(['schema.properties.a.const is not supported on type "array"']) + }) + + it('validates required: must be string[] naming declared properties', () => { + expect(violationsOf({ type: 'object', required: 'file' })) + .toEqual(['schema.required must be an array of strings']) + expect(violationsOf({ type: 'object', required: [1] })) + .toEqual(['schema.required must be an array of strings']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'string' } }, required: ['b'] })) + .toEqual(['schema.required names "b" which is not in properties']) + expect(violationsOf({ type: 'object', required: ['a'] })) + .toEqual(['schema.required names "a" which is not in properties']) + }) + + it('validates additionalProperties must be boolean and enum/const must be scalars', () => { + expect(violationsOf({ type: 'object', additionalProperties: {} })) + .toEqual(['schema.additionalProperties must be a boolean']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: [] } } })) + .toEqual(['schema.properties.a.enum must be a non-empty array of scalars']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: [{}] } } })) + .toEqual(['schema.properties.a.enum must be a non-empty array of scalars']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: 'x' } } })) + .toEqual(['schema.properties.a.enum must be a non-empty array of scalars']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'number', enum: [Number.NaN] } } })) + .toEqual(['schema.properties.a.enum must be a non-empty array of scalars']) + expect(violationsOf({ type: 'object', properties: { a: { type: 'string', const: {} } } })) + .toEqual(['schema.properties.a.const must be a scalar']) + }) + + it('rejects non-string description/title and non-JSON annotation payloads', () => { + expect(violationsOf({ type: 'object', description: 7 })) + .toEqual(['schema.description must be a string']) + expect(violationsOf({ type: 'object', title: 7 })) + .toEqual(['schema.title must be a string']) + expect(violationsOf({ type: 'object', default: () => 1 })) + .toEqual(['schema.default annotation must be JSON data']) + expect(violationsOf({ type: 'object', examples: [undefined] })) + .toEqual(['schema.examples annotation must be JSON data']) + expect(violationsOf({ type: 'object', examples: [Number.POSITIVE_INFINITY] })) + .toEqual(['schema.examples annotation must be JSON data']) + // A cyclic annotation payload is caught by the JSON-data walk. + const cyclicAnnotation: Record = {} + cyclicAnnotation.self = cyclicAnnotation + expect(violationsOf({ type: 'object', default: cyclicAnnotation })) + .toEqual(['schema.default annotation must be JSON data']) + // Object/array annotations that ARE JSON data pass. + asserted({ type: 'object', default: { a: [1, 'x', null, true] } }) + }) + + it('rejects a circular schema instead of recursing forever', () => { + const node: Record = { type: 'object' } + node.properties = { self: node } + expect(violationsOf(node)).toEqual(['schema.properties.self is circular']) + }) + + it('accepts the same subschema object reused in two SIBLING positions (a DAG, not a cycle)', () => { + const leaf = { type: 'string' } + asserted({ type: 'object', properties: { a: leaf, b: leaf } }) + }) +}) + +describe('validateStructuredValue', () => { + const schema = asserted({ + type: 'object', + properties: { + file: { type: 'string' }, + line: { type: 'integer' }, + score: { type: 'number' }, + confirmed: { type: 'boolean' }, + parent: { type: 'null' }, + severity: { type: 'string', enum: ['low', 'high'] }, + kind: { type: 'string', const: 'bug' }, + tags: { type: 'array', items: { type: 'string' } }, + free: { type: 'array' }, + nested: { type: 'object', properties: { x: { type: 'number' } }, required: ['x'], additionalProperties: false }, + }, + required: ['file'], + }) + + it('accepts a fully valid value (empty violations)', () => { + expect(validateStructuredValue(schema, { + file: 'a.ts', line: 3, score: 0.5, confirmed: true, parent: null, + severity: 'high', kind: 'bug', tags: ['x'], free: [1, { any: true }], nested: { x: 1 }, + })).toEqual([]) + }) + + it('reports missing required and wrong root type', () => { + expect(validateStructuredValue(schema, {})).toEqual(['missing required property "value.file"']) + expect(validateStructuredValue(schema, 'nope')).toEqual(['"value" must be an object']) + expect(validateStructuredValue(schema, [])).toEqual(['"value" must be an object']) + }) + + it('type-checks every scalar branch with path-qualified messages', () => { + expect(validateStructuredValue(schema, { file: 1 })).toEqual(['"value.file" must be a string']) + expect(validateStructuredValue(schema, { file: 'a', line: 1.5 })).toEqual(['"value.line" must be an integer']) + expect(validateStructuredValue(schema, { file: 'a', line: 'x' })).toEqual(['"value.line" must be an integer']) + expect(validateStructuredValue(schema, { file: 'a', score: 'x' })).toEqual(['"value.score" must be a finite number']) + expect(validateStructuredValue(schema, { file: 'a', score: Number.NaN })).toEqual(['"value.score" must be a finite number']) + expect(validateStructuredValue(schema, { file: 'a', confirmed: 'yes' })).toEqual(['"value.confirmed" must be a boolean']) + expect(validateStructuredValue(schema, { file: 'a', parent: 0 })).toEqual(['"value.parent" must be null']) + }) + + it('enforces enum membership and const equality', () => { + expect(validateStructuredValue(schema, { file: 'a', severity: 'mid' })) + .toEqual(['"value.severity" must be one of ["low","high"]']) + expect(validateStructuredValue(schema, { file: 'a', kind: 'feature' })) + .toEqual(['"value.kind" must be "bug"']) + }) + + it('checks arrays per index; an items-less array accepts anything', () => { + expect(validateStructuredValue(schema, { file: 'a', tags: 'x' })).toEqual(['"value.tags" must be an array']) + expect(validateStructuredValue(schema, { file: 'a', tags: ['ok', 2] })).toEqual(['"value.tags[1]" must be a string']) + expect(validateStructuredValue(schema, { file: 'a', free: [{ deep: [1] }, null] })).toEqual([]) + }) + + it('recurses into nested objects: required + additionalProperties: false', () => { + expect(validateStructuredValue(schema, { file: 'a', nested: {} })) + .toEqual(['missing required property "value.nested.x"']) + expect(validateStructuredValue(schema, { file: 'a', nested: { x: 1, y: 2 } })) + .toEqual(['"value.nested.y" is not a declared property (additionalProperties: false)']) + expect(validateStructuredValue(schema, { file: 'a', nested: 3 })) + .toEqual(['"value.nested" must be an object']) + }) + + it('a required key present-but-undefined counts as missing', () => { + expect(validateStructuredValue(schema, { file: undefined })).toEqual(['missing required property "value.file"']) + }) + + it('collects multiple violations across branches in one pass', () => { + expect(validateStructuredValue(schema, { line: 'x', severity: 'mid' })).toEqual([ + 'missing required property "value.file"', + '"value.line" must be an integer', + '"value.severity" must be one of ["low","high"]', + ]) + }) + + it('null-typed const/enum work through the scalar path', () => { + const nullish = asserted({ type: 'object', properties: { a: { type: 'null', const: null } } }) + expect(validateStructuredValue(nullish, { a: null })).toEqual([]) + }) + + it('rejects a non-object properties value in the schema walk', () => { + expect(violationsOf({ type: 'object', properties: [] })) + .toEqual(['schema.properties must be an object of schemas']) + }) + + it('an object schema without properties/required only type-checks its value', () => { + const bare = asserted({ type: 'object' }) + expect(validateStructuredValue(bare, { any: ['thing'] })).toEqual([]) + expect(validateStructuredValue(bare, 7)).toEqual(['"value" must be an object']) + }) + + it('validateStructuredValue throws on a type the assert would never let through (assertNever backstop)', () => { + const forged = { type: 'tuple' } as unknown as StructuredOutputSchema + expect(() => validateStructuredValue(forged, 1)).toThrow(/tuple/) + }) +}) diff --git a/packages/subagent/subagent-fork/README.md b/packages/subagent/subagent-fork/README.md index c691d56355..7b43f82261 100644 --- a/packages/subagent/subagent-fork/README.md +++ b/packages/subagent/subagent-fork/README.md @@ -12,12 +12,13 @@ The seam this rides on: `CreateAgentOptions.seed` (added on `dsh-agent`, threade ## Capabilities -`{ outputSchema: false, depthLimit: true, toolFilter: false }` — identical to spawn (the depth/model/output behavior is the shared driver's). +`{ outputSchema: true, depthLimit: true, toolFilter: false }` — identical to spawn (the depth/model/structured-output behavior is the shared driver's). ## Config | Key | Meaning | |---|---| | `providerName` | Registry name on `ctx.subagents` (default `fork`). | +| `structuredNudgeRetries` | How many times a structured run re-prompts a child that finished cleanly without calling `structured_output` (default 1). | See [`dsh-subagent-spawn`](../subagent-spawn/README.md) for the run lifecycle, model inheritance, and depth tracking — all shared. diff --git a/packages/subagent/subagent-fork/src/index.ts b/packages/subagent/subagent-fork/src/index.ts index 02c1811d82..39dfbfd440 100644 --- a/packages/subagent/subagent-fork/src/index.ts +++ b/packages/subagent/subagent-fork/src/index.ts @@ -25,19 +25,25 @@ import z from 'schemastery' import type { SessionEvent } from '@deepseek-ai/dsh-session' import type { Agent } from '@deepseek-ai/dsh-agent' import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } from '@deepseek-ai/dsh-subagent' -import { startInProcessRun } from '@deepseek-ai/dsh-subagent-inprocess' +import { acquireStructuredRuntime, startInProcessRun } from '@deepseek-ai/dsh-subagent-inprocess' export const name = 'subagent-fork' -export const inject = ['subagents', 'agents'] +export const inject = ['subagents', 'agents', 'tools'] -/** Config: the registry name to register the provider under. */ +/** Config: the registry name to register the provider under, plus structured-run tuning. */ export interface Config { /** Provider name on `ctx.subagents` (default `fork`). */ providerName: string + /** + * How many times a structured run re-prompts a child that finished cleanly + * without calling `structured_output` before giving up (default 1). + */ + structuredNudgeRetries: number } export const Config: z = z.object({ providerName: z.string().default('fork'), + structuredNudgeRetries: z.natural().default(1), }) /** @@ -57,18 +63,24 @@ export function completedTurnPrefix(parent: Agent): SessionEvent[] { } /** - * The fork provider. Supports `depthLimit`; NOT `outputSchema`/`toolFilter` this - * cut (the service rejects a request needing either before `start` runs). + * The fork provider. Supports `depthLimit` and `outputSchema` (via the shared + * in-process structured runtime); NOT `toolFilter` this cut (the service + * rejects a request needing it before `start` runs). */ class ForkProvider implements SubagentProvider { - readonly capabilities: SubagentCapabilities = { outputSchema: false, depthLimit: true, toolFilter: false } + readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: false } - constructor(readonly name: string, private readonly ctx: Context) {} + constructor( + readonly name: string, + private readonly ctx: Context, + private readonly structuredNudgeRetries: number, + ) {} start(request: SubagentStartRequest) { const seed = completedTurnPrefix(request.parent) return startInProcessRun(this.ctx, request, { providerName: this.name, + structuredNudgeRetries: this.structuredNudgeRetries, // Only pass a seed when there's a completed turn to inherit; an empty seed // is equivalent to a fresh child, so omit it to keep the session unseeded. ...seed.length > 0 ? { seed } : {}, @@ -77,5 +89,12 @@ class ForkProvider implements SubagentProvider { } export function apply(ctx: Context, config: Config): void { - ctx.subagents.registerProvider(new ForkProvider(config.providerName, ctx)) + // Hold the structured runtime for the plugin's lifetime (see the spawn + // backend — same two-level lifetime: backends for availability, runs for + // mid-run survival across a backend unload). + ctx.effect(() => { + const acquisition = acquireStructuredRuntime(ctx) + return () => { acquisition.release() } + }, 'subagent-fork structured runtime') + ctx.subagents.registerProvider(new ForkProvider(config.providerName, ctx, config.structuredNudgeRetries)) } diff --git a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts index 1f932fbaf9..82caf25948 100644 --- a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts +++ b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts @@ -30,8 +30,8 @@ async function setup(script: Script) { await ctx.plugin(Invariants) await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SubagentService) - await ctx.plugin(Spawn, { providerName: 'spawn' }) - await ctx.plugin(fork, { providerName: 'fork' }) + await ctx.plugin(Spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) + await ctx.plugin(fork, { providerName: 'fork', structuredNudgeRetries: 1 }) ctx.llm.registerAdapter(['mock'], new MockAdapter(script)) const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) return { ctx, parent } diff --git a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts index 56441a656f..4abba075c3 100644 --- a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts +++ b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts @@ -37,7 +37,7 @@ async function setup(script: Script) { await ctx.plugin(Invariants) await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SubagentService) - await ctx.plugin(fork, { providerName: 'fork' }) + await ctx.plugin(fork, { providerName: 'fork', structuredNudgeRetries: 1 }) ctx.llm.registerAdapter(['mock'], new MockAdapter(script)) const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) return { ctx, parent } @@ -161,16 +161,20 @@ describe('dsh-subagent-fork', () => { await run.dispose() }) - it('advertises depthLimit but not outputSchema/toolFilter', async () => { + it('advertises depthLimit and outputSchema but not toolFilter', async () => { const { ctx } = await setup([]) - expect(ctx.subagents.getProvider('fork')!.capabilities).toEqual({ outputSchema: false, depthLimit: true, toolFilter: false }) + expect(ctx.subagents.getProvider('fork')!.capabilities).toEqual({ outputSchema: true, depthLimit: true, toolFilter: false }) }) it('unregisters the provider when its fiber is disposed (HMR safety)', async () => { const ctx = new Context() await ctx.plugin(SubagentService) await ctx.plugin(AgentRegistry) - const fiber = await ctx.plugin(fork, { providerName: 'fork' }) + // The backend injects 'tools' for the structured runtime, so the registry + // (and its systemPrompt dependency) must be live for the fiber to activate. + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const fiber = await ctx.plugin(fork, { providerName: 'fork', structuredNudgeRetries: 1 }) expect(ctx.subagents.list()).toEqual(['fork']) await fiber.dispose() expect(ctx.subagents.list()).toEqual([]) @@ -179,12 +183,12 @@ describe('dsh-subagent-fork', () => { it('has the namespace-plugin export shape (no stray default)', () => { expect('default' in fork).toBe(false) expect(fork.name).toBe('subagent-fork') - expect(fork.inject).toEqual(['subagents', 'agents']) + expect(fork.inject).toEqual(['subagents', 'agents', 'tools']) const loader = Object.create(Loader.prototype) as Loader const unwrapped = loader.unwrapExports(fork) as Record expect(unwrapped).toBe(fork) expect(unwrapped.name).toBe('subagent-fork') - expect(unwrapped.inject).toEqual(['subagents', 'agents']) + expect(unwrapped.inject).toEqual(['subagents', 'agents', 'tools']) expect(typeof unwrapped.apply).toBe('function') }) }) diff --git a/packages/subagent/subagent-inprocess/README.md b/packages/subagent/subagent-inprocess/README.md index af6d5792a9..1cbdccaee6 100644 --- a/packages/subagent/subagent-inprocess/README.md +++ b/packages/subagent/subagent-inprocess/README.md @@ -8,16 +8,27 @@ The shared **in-process subagent run driver**. A pure library (no provider, no r Runs a child as a child [`Agent`](../../core/agent) on the same cordis context (`ctx.agents`): -1. computes child depth = `depthOf(parent) + 1`; if `request.maxDepth` is set and exceeded, throws `SubagentDepthError` (the `depthLimit` capability); -2. creates a child via `ctx.agents.create` with a fresh `AgentId`/`SessionId`, the parent's `cwd` + `parentSession` lineage, the optional `options.seed` (fork's completed-turn prefix; omitted for a fresh child), and `agentOptions` (the child inherits the **parent's model** by default — a child with no model can't run — overridable via `request.agentOptions.model`; the system prompt is NOT inherited); -3. drives the one-shot: `child.send(prompt)` then `await child.whenIdle()` (ordering matters — `send` enqueues synchronously, so `whenIdle` observes the queued work and resolves on the child's `running → idle` transition, never before the turn starts); -4. reads the result, scoped to the child's OWN events (everything at or after `seedLength`, so a seeded child that produced no message of its own never returns the seeded parent's last message): the last `assistant/message` content (deep-cloned — the log is frozen) and the last `turn/end.reason` mapped to a `SubagentStopReason`. +1. computes child depth = `depthOf(parent) + 1`; if `request.maxDepth` is set and exceeded, throws `SubagentDepthError` (the `depthLimit` capability); a `request.outputSchema` is asserted against the supported subset (`assertSupportedOutputSchema` from [dsh-tools](../../core/tools/README.md)) before any child exists; +2. creates a child via `ctx.agents.create` with a fresh `AgentId`/`SessionId`, the parent's `cwd` + `parentSession` lineage, the optional `options.seed` (fork's completed-turn prefix; omitted for a fresh child), and `agentOptions` (the child inherits the **parent's model** by default — a child with no model can't run — overridable via `request.agentOptions.model`; the system prompt is NOT inherited; a structured run appends the `structured_output` instruction after the caller's prompt); +3. drives the one-shot: `child.send(prompt)` then `await child.whenIdle()` (ordering matters — `send` enqueues synchronously, so `whenIdle` observes the queued work and resolves on the child's `running → idle` transition, never before the turn starts); a structured child that finished a turn CLEANLY without calling `structured_output` is re-prompted (a nudge — a fresh turn) up to `options.structuredNudgeRetries` times; +4. reads the result, scoped to the child's OWN events (everything at or after `seedLength`, so a seeded child that produced no message of its own never returns the seeded parent's last message): the last `assistant/message` content (deep-cloned — the log is frozen) and the last `turn/end.reason` mapped to a `SubagentStopReason`. A structured run surfaces the captured value as `result.structured`; a structured child that finished cleanly WITHOUT ever capturing settles `error` (a clean finish without the demanded result is a failure, not a success with a missing field). `dispose()` delegates to `AgentHandle.dispose()` (stop loop → await quiescence → remove session); `cancel()` cancels the child's in-flight turn. A cancel landing before any `turn/end` (the pre-turn window) still settles `aborted`, honoring the cancel contract rather than the generic no-turn `error`. ### `InProcessRunOptions` -`{ providerName: string; seed?: SessionEvent[] }` — the per-backend inputs: the provider name (for error context) and the optional child-session seed. +`{ providerName: string; seed?: SessionEvent[]; structuredNudgeRetries: number }` — the per-backend inputs: the provider name (for error context), the optional child-session seed, and the structured-run nudge budget (REQUIRED, resolved from the backend's validated Config — the driver never fills it with a hidden default). + +### Structured output: `acquireStructuredRuntime(ctx): StructuredAcquisition` + +The mechanism behind `outputSchema` for in-process children. One globally registered `structured_output` capture tool (its registered parameters are a placeholder) plus two listeners, registered once per root context and shared by every holder: + +- an `agent/request` waterfall listener registered `prepend: true` that post-processes `await next()` — **final-request enforcement**: the request that hits the wire never carries `structured_output` for an agent without a structured run, and always carries the run's OWN schema (as the tool's `parameters`) for one that has it. Per-agent shaping lives here because the tool registry and prompt assembly are context-global while schemas differ per concurrent child; cooperative mutate-then-`next()` would not survive a downstream listener returning a replacement request. +- an `agent/turn-continuation` listener that stops a child's turn once its output is captured, so a successful capture doesn't buy a wasted extra model step. + +The capture tool validates each call against the run's schema (`validateStructuredValue`) — violations become an `INVALID_ARGS` isError result the model retries in-turn; a valid call records the value. + +Lifetime is refcounted with two kinds of holder: each backend acquires for its plugin lifetime (`apply`), and each structured RUN holds its own acquisition from start to settle — so unregistration can never precede a live run's settle, and the runtime disposes only when the last backend AND the last run are gone. `release()` is idempotent per acquisition. ### `depthOf(agent): number` diff --git a/packages/subagent/subagent-inprocess/package.json b/packages/subagent/subagent-inprocess/package.json index f3bd774554..41c46e00d3 100644 --- a/packages/subagent/subagent-inprocess/package.json +++ b/packages/subagent/subagent-inprocess/package.json @@ -26,6 +26,7 @@ "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", "@deepseek-ai/dsh-subagent": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "devDependencies": { diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts index 4b8d2d4c99..4293505995 100644 --- a/packages/subagent/subagent-inprocess/src/index.ts +++ b/packages/subagent/subagent-inprocess/src/index.ts @@ -18,7 +18,22 @@ import type { Context } from 'cordis' import { AgentId, type Agent, type AgentHandle, type AgentOptions } from '@deepseek-ai/dsh-agent' import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import { assertSupportedOutputSchema } from '@deepseek-ai/dsh-tools' import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent' +import { + acquireStructuredRuntime, + STRUCTURED_OUTPUT_INSTRUCTION, + STRUCTURED_OUTPUT_NUDGE, + type StructuredAcquisition, +} from './structured.ts' + +export { + acquireStructuredRuntime, + STRUCTURED_OUTPUT_TOOL, + STRUCTURED_OUTPUT_INSTRUCTION, + STRUCTURED_OUTPUT_NUDGE, + type StructuredAcquisition, +} from './structured.ts' declare module '@deepseek-ai/dsh-agent' { interface AgentOptions { @@ -76,6 +91,13 @@ export interface InProcessRunOptions { * parent's log (FORK), or `undefined` for a fresh child (SPAWN). */ readonly seed?: SessionEvent[] + /** + * How many times a structured run re-prompts a child that finished a turn + * cleanly WITHOUT calling `structured_output` (see the structured module). + * REQUIRED, resolved from the backend's validated Config — per the explicit- + * defaulting rule, the driver never fills it with a hidden fallback. + */ + readonly structuredNudgeRetries: number } /** @@ -98,6 +120,10 @@ export function startInProcessRun( if (request.maxDepth !== undefined && childDepth > request.maxDepth) { throw new SubagentDepthError(childDepth, request.maxDepth) } + // Assert the schema subset BEFORE any child exists (the service has already + // capability-gated; this rejects a schema outside the enforced subset loud). + const schema = request.outputSchema + if (schema !== undefined) assertSupportedOutputSchema(schema) const childId = AgentId(randomUUID()) // The child's OWN events begin after the seed (fork seeds the parent's @@ -109,13 +135,24 @@ export function startInProcessRun( // Inherit the parent's model by default (a child with no model cannot run); // an explicit `request.agentOptions.model` overrides it. The parent's // systemPrompt is NOT inherited — a fresh child is a clean specialist unless - // the caller supplies one. + // the caller supplies one. A structured run appends the structured_output + // instruction after whatever prompt the caller supplied. + const callerPrompt = request.agentOptions?.systemPrompt + const systemPrompt = schema === undefined + ? callerPrompt + : [callerPrompt, STRUCTURED_OUTPUT_INSTRUCTION].filter(text => text !== undefined && text.length > 0).join('\n\n') const agentOptions: AgentOptions = { ...request.parent.options.model !== undefined ? { model: request.parent.options.model } : {}, ...request.agentOptions, + ...systemPrompt !== undefined ? { systemPrompt } : {}, subagentDepth: childDepth, } + // The structured runtime is held for the WHOLE run (acquired before the child + // exists, released when the result settles), so a backend hot-reload mid-run + // cannot unregister the capture tool out from under this live child. + const structured: StructuredAcquisition | undefined = schema !== undefined ? acquireStructuredRuntime(ctx) : undefined + const handle: AgentHandle = ctx.agents.create({ agentId: childId, sessionId: SessionId(randomUUID()), @@ -130,6 +167,7 @@ export function startInProcessRun( agentOptions, }) const child = handle.agent + if (structured && schema !== undefined) structured.attach(child, schema) // Bridge the request's abort signal to the child (the consumer also bridges // its own exec.signal, but a backend-level bridge keeps the contract local). @@ -154,9 +192,30 @@ export function startInProcessRun( if (request.signal?.aborted) return { output: [], stopReason: 'aborted' } child.send(request.prompt) await child.whenIdle() - return readResult(child, seedLength, cancelled) + if (structured) { + // Nudge loop: a child that finished a turn CLEANLY without calling + // structured_output gets re-prompted, up to the backend-configured + // retry count. An errored/aborted turn is not nudged — its failure is + // the honest result. (This also covers a cancel: a cancelled turn ends + // `aborted`, and a pre-turn cancel leaves no `turn/end` at all, so + // neither reads `completed`.) + let nudges = options.structuredNudgeRetries + while ( + structured.captured(child) === undefined && nudges > 0 + && lastOwnTurnEnd(child, seedLength)?.data.reason.kind === 'completed' + ) { + nudges -= 1 + child.send([{ type: 'text', text: STRUCTURED_OUTPUT_NUDGE }]) + await child.whenIdle() + } + } + return readResult(child, seedLength, cancelled, structured ? { captured: structured.captured(child) } : undefined) } finally { request.signal?.removeEventListener('abort', onAbort) + if (structured) { + structured.detach(child) + structured.release() + } } })() @@ -173,6 +232,12 @@ export function startInProcessRun( } } +/** The child's OWN last `turn/end` event (events at or after `seedLength`), if any. */ +function lastOwnTurnEnd(child: Agent, seedLength: number): SessionEvent<'turn/end'> | undefined { + return child.session.events.slice(seedLength) + .findLast((e): e is SessionEvent<'turn/end'> => e.type === 'turn/end') +} + /** * Read a settled child's terminal result from its session log, scoped to the * child's OWN events (everything at or after `seedLength` — fork seeds the @@ -184,12 +249,29 @@ export function startInProcessRun( * logged (a cancel landed in the pre-turn window, before any turn ran), the * run settles `aborted` per the {@link SubagentRun.cancel} contract rather than * the generic no-turn `error`. + * + * A structured run (`structured` present) additionally reports the captured + * value on {@link SubagentResult.structured}. A structured child that finished + * CLEANLY without ever capturing (the nudges ran out) settles `error` — a clean + * finish without the demanded structured result is a failure, not a success + * with a missing field; a non-`completed` reason keeps its own honest mapping. */ -function readResult(child: Agent, seedLength: number, cancelled: boolean): SubagentResult { +function readResult( + child: Agent, + seedLength: number, + cancelled: boolean, + structured?: { captured?: { value: unknown } | undefined }, +): SubagentResult { const own = child.session.events.slice(seedLength) const lastMessage = own.findLast((e): e is SessionEvent<'assistant/message'> => e.type === 'assistant/message') const lastEnd = own.findLast((e): e is SessionEvent<'turn/end'> => e.type === 'turn/end') const output: ContentBlock[] = lastMessage ? structuredClone(lastMessage.data.content) : [] - if (lastEnd === undefined && cancelled) return { output, stopReason: 'aborted' } - return { output, stopReason: toStopReason(lastEnd?.data.reason) } + const stopReason: SubagentStopReason = lastEnd === undefined && cancelled + ? 'aborted' + : toStopReason(lastEnd?.data.reason) + if (structured) { + if (structured.captured) return { output, structured: structured.captured.value, stopReason } + if (stopReason === 'completed') return { output, stopReason: 'error' } + } + return { output, stopReason } } diff --git a/packages/subagent/subagent-inprocess/src/structured.ts b/packages/subagent/subagent-inprocess/src/structured.ts new file mode 100644 index 0000000000..da371ac8f4 --- /dev/null +++ b/packages/subagent/subagent-inprocess/src/structured.ts @@ -0,0 +1,193 @@ +/** + * Structured-output support for the in-process subagent backends: the mechanism + * behind `SubagentStartRequest.outputSchema` for children that run as agents on + * the same context. + * + * The model-facing surface is one globally registered `structured_output` tool + * whose REGISTERED parameters are a placeholder — the real schema is per run. + * Because the tool registry and prompt assembly are context-global while + * schemas differ per child (two concurrent structured runs may carry different + * schemas), per-agent shaping happens on the `agent/request` waterfall with a + * `prepend: true` listener that post-processes `await next()` — FINAL-REQUEST + * enforcement: whatever downstream listeners mutated or replaced, the request + * that hits the wire never carries `structured_output` for an agent without a + * structured run, and always carries the run's OWN schema for one that has it. + * (Cooperative mutate-then-`next()` would not survive a downstream listener + * returning a replacement request — see the waterfall composition caveat in + * docs/architecture.md.) + * + * A companion `agent/turn-continuation` listener stops a child's turn once its + * output is captured — without it, the loop's default "had tool calls ⇒ + * continue" buys a wasted extra model step per structured child. + * + * Lifetime is refcounted with two kinds of holder: each backend acquires for + * its plugin lifetime (so the tool exists before any run), and each structured + * RUN acquires from start to settle (so a backend hot-reload mid-run cannot + * unregister the capture tool out from under a live child). Registrations are + * effects on the ROOT context — their natural upper bound is app teardown — and + * the refcount disposes them when the last holder releases. + * + * @module @deepseek-ai/dsh-subagent-inprocess/structured + */ + +import type { Context } from 'cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { ContentBlock, GenerateOptions, ToolSchema } from '@deepseek-ai/dsh-llm' +import type { ContinuationDecision } from '@deepseek-ai/dsh-agent' +import type { ToolExecution } from '@deepseek-ai/dsh-tools' +import { ToolArgsError, validateStructuredValue, type StructuredOutputSchema } from '@deepseek-ai/dsh-tools' + +/** The model-facing tool name a structured child must call to finish. */ +export const STRUCTURED_OUTPUT_TOOL = 'structured_output' + +/** The per-child instruction appended to a structured child's system prompt. */ +export const STRUCTURED_OUTPUT_INSTRUCTION + = 'When you have your final answer, you MUST report it by calling the ' + + `\`${STRUCTURED_OUTPUT_TOOL}\` tool with arguments matching its parameter schema exactly. ` + + 'Do not finish with a plain text answer: only the tool call counts as your result.' + +/** The nudge sent when a structured child finishes cleanly without calling the tool. */ +export const STRUCTURED_OUTPUT_NUDGE + = `You finished without calling \`${STRUCTURED_OUTPUT_TOOL}\`. ` + + `Call \`${STRUCTURED_OUTPUT_TOOL}\` now with your final result matching its parameter schema.` + +/** One structured run's state: the schema to enforce and the captured value, once recorded. */ +interface RunState { + readonly schema: StructuredOutputSchema + captured?: { value: unknown } +} + +/** The per-root-context runtime: run states plus the shared registrations. */ +interface StructuredRuntime { + refs: number + readonly states: WeakMap + readonly disposers: (() => void)[] +} + +/** One root context ⇒ one runtime (multi-app test isolation). */ +const runtimes = new WeakMap() + +/** + * One holder's handle on the shared structured runtime. `release()` is + * idempotent per acquisition; the runtime's registrations are disposed when the + * LAST holder (backend plugin or live run) releases. + */ +export interface StructuredAcquisition { + /** Enforce `schema` on `agent`'s requests and start capturing its `structured_output` call. */ + attach(agent: Agent, schema: StructuredOutputSchema): void + /** The captured value, once the child called the tool with valid arguments. */ + captured(agent: Agent): { value: unknown } | undefined + /** Stop enforcing/capturing for `agent` (WeakMap-backed; safe to call twice). */ + detach(agent: Agent): void + /** Drop this holder's reference (idempotent); the last release unregisters everything. */ + release(): void +} + +/** + * Acquire the per-root-context structured runtime, registering the capture tool + * and the two waterfall listeners on the FIRST acquisition. See the module doc + * for the enforcement and lifetime design. + * @param ctx - any context of the app; the runtime keys off `ctx.root`. + * @returns this holder's handle (attach/captured/detach + idempotent release). + */ +export function acquireStructuredRuntime(ctx: Context): StructuredAcquisition { + const root: Context = ctx.root + let runtime = runtimes.get(root) + if (!runtime) { + runtime = { refs: 0, states: new WeakMap(), disposers: [] } + runtimes.set(root, runtime) + registerRuntime(root, runtime) + } + runtime.refs += 1 + + let released = false + return { + attach(agent: Agent, schema: StructuredOutputSchema): void { + runtime.states.set(agent, { schema }) + }, + captured(agent: Agent): { value: unknown } | undefined { + return runtime.states.get(agent)?.captured + }, + detach(agent: Agent): void { + runtime.states.delete(agent) + }, + release(): void { + if (released) return + released = true + runtime.refs -= 1 + if (runtime.refs > 0) return + runtimes.delete(root) + for (const dispose of runtime.disposers.splice(0)) dispose() + }, + } +} + +/** Register the capture tool + the two listeners on the root context (first acquire). */ +function registerRuntime(root: Context, runtime: StructuredRuntime): void { + // The registered parameters are a PLACEHOLDER: the request listener below + // swaps in the run's real schema per child, and strips the tool entirely for + // every agent without a structured run — so this shape is never model-visible. + runtime.disposers.push(root.tools.register({ + name: STRUCTURED_OUTPUT_TOOL, + description: + 'Report your final structured result. Call this exactly once, when your answer is complete; ' + + 'the arguments must match this tool\'s parameter schema exactly.', + parameters: { type: 'object', properties: {} }, + execute(args: unknown, exec: ToolExecution): Promise { + const state = exec.agent ? runtime.states.get(exec.agent) : undefined + if (!state) { + // Reachable only if a non-structured agent somehow calls the tool (the + // request listener strips it, so the model never sees it) — fail loud + // rather than capture into nowhere. + throw new Error(`${STRUCTURED_OUTPUT_TOOL} is only available to subagents started with an output schema`) + } + const violations = validateStructuredValue(state.schema, args) + // ToolArgsError → isError result with INVALID_ARGS: the model retries + // within the same turn, exactly like a schema-validated defineTool call. + if (violations.length > 0) throw new ToolArgsError(violations) + state.captured = { value: args } + return Promise.resolve([{ type: 'text', text: 'Structured output recorded.' }]) + }, + })) + + // FINAL-REQUEST enforcement (prepend: true = first registered = OUTERMOST + // wrapper): post-process whatever the downstream listeners and the core + // produced, so a downstream listener returning a replacement request cannot + // leak the tool to other agents or erase the child's schema. + runtime.disposers.push(root.on('agent/request', async function ( + this: unknown, agent: Agent, _turn: number, _step: number, _options: GenerateOptions, next: () => Promise, + ): Promise { + const final = await next() + const state = runtime.states.get(agent) + if (state) { + const schemaEntry: ToolSchema = { + name: STRUCTURED_OUTPUT_TOOL, + description: + 'Report your final structured result. Call this exactly once, when your answer is complete; ' + + 'the arguments must match this tool\'s parameter schema exactly.', + // ToolSchema.parameters is the wire-level JSON Schema object; the + // asserted subset type is structurally exactly that. + parameters: state.schema as unknown as Record, + } + final.tools = [...(final.tools ?? []).filter(tool => tool.name !== STRUCTURED_OUTPUT_TOOL), schemaEntry] + return final + } + // No structured run: strip the placeholder if present; leave an absent + // tools field absent (an adapter may treat `tools: []` and no tools + // differently on the wire). + if (final.tools?.some(tool => tool.name === STRUCTURED_OUTPUT_TOOL)) { + final.tools = final.tools.filter(tool => tool.name !== STRUCTURED_OUTPUT_TOOL) + } + return final + }, { prepend: true })) + + // Stop a structured child's turn once its output is captured: the default + // "had tool calls ⇒ continue" would otherwise buy a wasted extra model step + // after every successful capture. + runtime.disposers.push(root.on('agent/turn-continuation', function ( + this: unknown, agent: Agent, _turn: number, _decision: ContinuationDecision, next: () => Promise, + ): Promise { + if (runtime.states.get(agent)?.captured) return Promise.resolve({ action: 'stop' }) + return next() + })) +} diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts new file mode 100644 index 0000000000..643000de2c --- /dev/null +++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts @@ -0,0 +1,393 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService, { type GenerateOptions } from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import * as Invariants from '@deepseek-ai/dsh-invariants' +import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent' +import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' +import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +import * as spawn from '../../subagent-spawn/src/index.ts' +import * as fork from '../../subagent-fork/src/index.ts' +import { + acquireStructuredRuntime, + STRUCTURED_OUTPUT_INSTRUCTION, + STRUCTURED_OUTPUT_TOOL, +} from '../src/structured.ts' + +type Script = ConstructorParameters[0] + +const SCHEMA: StructuredOutputSchema = { + type: 'object', + properties: { answer: { type: 'number' }, note: { type: 'string' } }, + required: ['answer'], +} + +/** + * Real loop + scripted mock model + the REAL spawn backend (which acquires the + * structured runtime at apply, exactly as shipped). The mock model script + * drives the child's structured_output calls. + */ +async function setup(script: Script, options?: { nudges?: number; withFork?: boolean }) { + const ctx = new Context() + const adapter = new MockAdapter(script) + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(Invariants) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(SubagentService) + const fiber = await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: options?.nudges ?? 1 }) + const forkFiber = options?.withFork + ? await ctx.plugin(fork, { providerName: 'fork', structuredNudgeRetries: options?.nudges ?? 1 }) + : undefined + ctx.llm.registerAdapter(['mock'], adapter) + const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) + return { ctx, parent, adapter, fiber, forkFiber } +} + +function structuredRequest(parent: SubagentStartRequest['parent'], extra?: Partial): SubagentStartRequest { + return { prompt: [{ type: 'text', text: 'produce the answer' }], parent, outputSchema: SCHEMA, ...extra } +} + +/** The tool names of one recorded model request. */ +function toolNames(request: GenerateOptions): string[] { + return (request.tools ?? []).map(tool => tool.name) +} + +describe('in-process structured output', () => { + it('captures a valid structured_output call and surfaces result.structured', async () => { + const { ctx, parent } = await setup([ + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 42, note: 'done' }), + ]) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.stopReason).toBe('completed') + expect(result.structured).toEqual({ answer: 42, note: 'done' }) + await run.dispose() + }) + + it('stops the turn after a successful capture — no extra model step is spent', async () => { + const { ctx, parent, adapter } = await setup([ + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 }), + textResponse('MUST NOT BE CONSUMED'), + ]) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + await run.result + // Default continuation would run a second step after the tool call; the + // structured runtime's turn-continuation veto stops the turn instead. + expect(adapter.requests.length).toBe(1) + await run.dispose() + }) + + it('an invalid call gets an INVALID_ARGS isError result and the model retries in-turn', async () => { + const { ctx, parent } = await setup([ + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 'not-a-number' }), + toolCallResponse('c2', STRUCTURED_OUTPUT_TOOL, { answer: 7 }), + ]) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.structured).toEqual({ answer: 7 }) + expect(result.stopReason).toBe('completed') + // The child's log carries the isError tool/result for the invalid call. + const child = ctx.agents.get(run.id)! + const results = child.session.events.filter(e => e.type === 'tool/result') + expect(results.length).toBe(2) + expect((results[0]!.data as { isError?: boolean }).isError).toBe(true) + await run.dispose() + }) + + it('nudges a child that finished cleanly without calling the tool, then captures', async () => { + const { ctx, parent } = await setup([ + textResponse('here is my answer in prose'), + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 3 }), + ]) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.structured).toEqual({ answer: 3 }) + expect(result.stopReason).toBe('completed') + // The nudge is a real user-visible message in the child's log. + const child = ctx.agents.get(run.id)! + const users = child.session.events.filter(e => e.type === 'user/message') + expect(users.length).toBe(2) + await run.dispose() + }) + + it('settles error when the nudges run out without a capture', async () => { + const { ctx, parent, adapter } = await setup([ + textResponse('prose only'), + textResponse('still prose'), + ], { nudges: 1 }) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.stopReason).toBe('error') + expect(result.structured).toBeUndefined() + expect(adapter.requests.length).toBe(2) + await run.dispose() + }) + + it('zero nudge retries fails immediately after the first clean prose finish', async () => { + const { ctx, parent, adapter } = await setup([textResponse('prose')], { nudges: 0 }) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.stopReason).toBe('error') + expect(adapter.requests.length).toBe(1) + await run.dispose() + }) + + it('a child that errored is NOT nudged (its failure is the honest result)', async () => { + // Script exhaustion on the first call → the child turn errors. + const { ctx, parent, adapter } = await setup([], { nudges: 3 }) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.stopReason).toBe('error') + expect(adapter.requests.length).toBe(1) + await run.dispose() + }) + + it('rejects a schema outside the subset loud, before any child exists', async () => { + const { ctx, parent } = await setup([]) + expect(() => ctx.subagents.start('spawn', structuredRequest(parent, { + outputSchema: { type: 'object', oneOf: [] } as unknown as StructuredOutputSchema, + }))).toThrow(/unsupported output schema/) + expect(ctx.agents.get(AgentId('parent'))).toBeDefined() + }) + + it('appends the structured instruction to the child system prompt (caller prompt preserved)', async () => { + const { ctx, parent } = await setup([toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 })]) + const run = ctx.subagents.start('spawn', structuredRequest(parent, { + agentOptions: { systemPrompt: 'You are a counter.' }, + })) + await run.result + const child = ctx.agents.get(run.id)! + expect(child.options.systemPrompt).toBe(`You are a counter.\n\n${STRUCTURED_OUTPUT_INSTRUCTION}`) + await run.dispose() + }) + + it('a structured child WITHOUT a caller prompt gets exactly the instruction', async () => { + const { ctx, parent } = await setup([toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 })]) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + await run.result + const child = ctx.agents.get(run.id)! + expect(child.options.systemPrompt).toBe(STRUCTURED_OUTPUT_INSTRUCTION) + await run.dispose() + }) + + describe('final-request enforcement (the prepend agent/request listener)', () => { + it('a structured child sees structured_output with ITS schema; a plain agent never sees the tool', async () => { + const { ctx, parent, adapter } = await setup([ + // Parent turn (a plain agent): must NOT see the tool. + textResponse('parent answer'), + // Child turn: must see it, with the run's schema. + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 42 }), + ]) + parent.send([{ type: 'text', text: 'hello' }]) + await parent.whenIdle() + expect(toolNames(adapter.requests[0]!)).not.toContain(STRUCTURED_OUTPUT_TOOL) + + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + await run.result + const childRequest = adapter.requests[1]! + expect(toolNames(childRequest)).toContain(STRUCTURED_OUTPUT_TOOL) + const entry = childRequest.tools!.find(tool => tool.name === STRUCTURED_OUTPUT_TOOL)! + expect(entry.parameters).toEqual(SCHEMA) + await run.dispose() + }) + + it('two concurrent structured children each see their OWN schema', async () => { + const otherSchema: StructuredOutputSchema = { + type: 'object', + properties: { verdict: { type: 'string', enum: ['real', 'bogus'] } }, + required: ['verdict'], + } + const { ctx, parent, adapter } = await setup([ + (options: GenerateOptions) => { + // Answer with whatever schema this child was given — proves each + // request carried the right one regardless of scheduling order. + const entry = options.tools!.find(tool => tool.name === STRUCTURED_OUTPUT_TOOL)! + const args = 'verdict' in (entry.parameters.properties as Record) + ? { verdict: 'real' } + : { answer: 1 } + return toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, args) + }, + (options: GenerateOptions) => { + const entry = options.tools!.find(tool => tool.name === STRUCTURED_OUTPUT_TOOL)! + const args = 'verdict' in (entry.parameters.properties as Record) + ? { verdict: 'real' } + : { answer: 1 } + return toolCallResponse('c2', STRUCTURED_OUTPUT_TOOL, args) + }, + ]) + const runA = ctx.subagents.start('spawn', structuredRequest(parent)) + const runB = ctx.subagents.start('spawn', structuredRequest(parent, { outputSchema: otherSchema })) + const [a, b] = await Promise.all([runA.result, runB.result]) + expect(a.structured).toEqual({ answer: 1 }) + expect(b.structured).toEqual({ verdict: 'real' }) + const schemas = adapter.requests.map(request => + request.tools!.find(tool => tool.name === STRUCTURED_OUTPUT_TOOL)!.parameters) + expect(schemas).toContainEqual(SCHEMA) + expect(schemas).toContainEqual(otherSchema) + await runA.dispose() + await runB.dispose() + }) + + it('wins against a downstream listener that REPLACES the request object', async () => { + const { ctx, parent, adapter } = await setup([ + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 5 }), + ]) + // A downstream (non-prepend) listener that returns a brand-new request — + // the composition caveat that erases cooperative mutations. Registered + // AFTER the runtime's prepend listener, so it runs INSIDE it. + ctx.on('agent/request', async (_agent, _turn, _step, _options, next) => { + const replaced = await next() + return { ...replaced, tools: [...(replaced.tools ?? [])] } + }) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const result = await run.result + expect(result.structured).toEqual({ answer: 5 }) + const entry = adapter.requests[0]!.tools!.find(tool => tool.name === STRUCTURED_OUTPUT_TOOL) + expect(entry).toBeDefined() + expect(entry!.parameters).toEqual(SCHEMA) + await run.dispose() + }) + + it('a non-structured agent request keeps tools ABSENT when it had none (no tools: [] materialized)', async () => { + const { parent, adapter } = await setup([ + // The registry contributes the placeholder via prompt assembly, so + // tools is an array in the raw request — but after stripping the + // placeholder (its ONLY entry), the field must not be re-added as a + // different shape. + textResponse('plain'), + ]) + parent.send([{ type: 'text', text: 'q' }]) + await parent.whenIdle() + const request = adapter.requests[0]! + expect(toolNames(request)).not.toContain(STRUCTURED_OUTPUT_TOOL) + await new Promise(resolve => setTimeout(resolve, 0)) + }) + + it('handles a request with NO tools field at all, for plain and structured agents alike', async () => { + // Drive the waterfall directly with a toolless request — the enforcement + // listener must tolerate `tools: undefined` on both branches: leave it + // absent for a plain agent, and create the array for a structured child. + const { ctx, parent } = await setup([]) + const bare: GenerateOptions = { model: 'mock', messages: [] } + const plain = await ctx.waterfall('agent/request', parent, 1, 1, bare, () => Promise.resolve(bare)) + expect(plain.tools).toBeUndefined() + + const acquisition = acquireStructuredRuntime(ctx) + acquisition.attach(parent, SCHEMA) + const bare2: GenerateOptions = { model: 'mock', messages: [] } + const shaped = await ctx.waterfall('agent/request', parent, 1, 1, bare2, () => Promise.resolve(bare2)) + expect(shaped.tools!.map(tool => tool.name)).toEqual([STRUCTURED_OUTPUT_TOOL]) + acquisition.detach(parent) + acquisition.release() + }) + }) + + describe('runtime lifetime (refcount: backends + live runs)', () => { + it('registers the capture tool while a backend is loaded and unregisters when the last unloads', async () => { + const { ctx, fiber, forkFiber } = await setup([], { withFork: true }) + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeDefined() + await fiber.dispose() + // fork still holds a reference. + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeDefined() + await forkFiber!.dispose() + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined() + }) + + it('a live run-level acquisition keeps the runtime registered after EVERY backend unloads', async () => { + // Simulates the run-holder half of the two-level lifetime: a structured + // run acquires at start and releases at settle, so registration ordering + // is settle-then-unregister even if all backends unload first. (A real + // in-process child dies WITH its backend's fiber — the acquisition's + // observable job is this ordering, which a manual holder pins directly.) + const { ctx, fiber, forkFiber } = await setup([], { withFork: true }) + const runHolder = acquireStructuredRuntime(ctx) + await fiber.dispose() + await forkFiber!.dispose() + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeDefined() + runHolder.release() + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined() + }) + + it('a structured run releases its acquisition when it settles (backend unload mid-run)', async () => { + const { ctx, parent, fiber } = await setup(['hang']) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + // Let the child's step start streaming, then unload the backend. The + // backend owns the child agent, so the unload tears the child down and + // the run settles — releasing its own acquisition on the way out. + await new Promise(resolve => setTimeout(resolve, 30)) + await fiber.dispose() + const result = await run.result + expect(result.stopReason).toBe('error') + // Both holders (backend + run) released — nothing keeps the runtime now. + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined() + await run.dispose() + }) + + it('fork children capture structured output through the same runtime', async () => { + const { ctx, parent } = await setup([ + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 9 }), + ], { withFork: true }) + const run = ctx.subagents.start('fork', structuredRequest(parent)) + const result = await run.result + expect(result.structured).toEqual({ answer: 9 }) + await run.dispose() + }) + + it('acquisition release is idempotent (double release cannot underflow the refcount)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const first = acquireStructuredRuntime(ctx) + const second = acquireStructuredRuntime(ctx) + first.release() + first.release() + // The second holder still keeps the tool registered. + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeDefined() + second.release() + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined() + }) + + it('attach/captured/detach manage per-agent state through the acquisition surface', async () => { + const { ctx, parent } = await setup([]) + const acquisition = acquireStructuredRuntime(ctx) + expect(acquisition.captured(parent)).toBeUndefined() + acquisition.attach(parent, SCHEMA) + expect(acquisition.captured(parent)).toBeUndefined() + acquisition.detach(parent) + acquisition.detach(parent) + acquisition.release() + // The backend still holds its own reference from setup(). + expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeDefined() + }) + }) + + it('a direct structured_output call from an agent WITHOUT a structured run is an isError', async () => { + const { ctx, parent } = await setup([]) + const result = await ctx.tools.execute({ + callId: 'x' as never, + name: STRUCTURED_OUTPUT_TOOL, + arguments: { answer: 1 }, + agent: parent, + }) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ type: 'text' }) + }) + + it('a structured_output call with NO calling agent at all is an isError', async () => { + const { ctx } = await setup([]) + const result = await ctx.tools.execute({ + callId: 'x' as never, + name: STRUCTURED_OUTPUT_TOOL, + arguments: { answer: 1 }, + }) + expect(result.isError).toBe(true) + }) +}) diff --git a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts index 7219e03988..d3870ae51a 100644 --- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts @@ -51,7 +51,7 @@ describe('depthOf', () => { describe('startInProcessRun', () => { it('drives a fresh child (no seed) to completion and returns its output', async () => { const { ctx, parent } = await setup([textResponse('driver child answer')]) - const run = startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'do X' }], parent }, { providerName: 'spawn' }) + const run = startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'do X' }], parent }, { providerName: 'spawn', structuredNudgeRetries: 1 }) const result = await run.result expect(result.stopReason).toBe('completed') expect(text(result.output)).toBe('driver child answer') @@ -61,7 +61,7 @@ describe('startInProcessRun', () => { it('throws SubagentDepthError when the child would exceed maxDepth', async () => { const { ctx, parent } = await setup([]) - expect(() => startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'p' }], parent, maxDepth: 0 }, { providerName: 'spawn' })) + expect(() => startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'p' }], parent, maxDepth: 0 }, { providerName: 'spawn', structuredNudgeRetries: 1 })) .toThrow(SubagentDepthError) }) @@ -73,7 +73,7 @@ describe('startInProcessRun', () => { parent.send([{ type: 'text', text: 'parent q' }]) await parent.whenIdle() const seed = parent.session.events.slice() - const run = startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'child q' }], parent }, { providerName: 'fork', seed }) + const run = startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'child q' }], parent }, { providerName: 'fork', structuredNudgeRetries: 1, seed }) const result = await run.result expect(result.stopReason).toBe('completed') expect(text(result.output)).toBe('seeded child reply') diff --git a/packages/subagent/subagent-inprocess/tsconfig.json b/packages/subagent/subagent-inprocess/tsconfig.json index 4cb435d4fb..a52684ee6e 100644 --- a/packages/subagent/subagent-inprocess/tsconfig.json +++ b/packages/subagent/subagent-inprocess/tsconfig.json @@ -25,6 +25,9 @@ }, { "path": "../subagent" + }, + { + "path": "../../core/tools" } ] } diff --git a/packages/subagent/subagent-spawn/README.md b/packages/subagent/subagent-spawn/README.md index 97dfae9304..059c996215 100644 --- a/packages/subagent/subagent-spawn/README.md +++ b/packages/subagent/subagent-spawn/README.md @@ -6,14 +6,15 @@ The run mechanics live in the shared [`@deepseek-ai/dsh-subagent-inprocess`](../ ## What it does -`start(request)` delegates to `startInProcessRun(ctx, request, { providerName })` with no seed: a fresh child agent with the parent's `cwd`/`parentSession` lineage and (by default) the parent's model. See the [driver README](../subagent-inprocess/README.md) for the full lifecycle (depth check, one-shot drive, result read, dispose). +`start(request)` delegates to `startInProcessRun(ctx, request, { providerName, structuredNudgeRetries })` with no seed: a fresh child agent with the parent's `cwd`/`parentSession` lineage and (by default) the parent's model. See the [driver README](../subagent-inprocess/README.md) for the full lifecycle (depth check, one-shot drive, result read, dispose). ## Capabilities -`{ outputSchema: false, depthLimit: true, toolFilter: false }`. It constructs the child, so it enforces a recursion cap; structured output and tool-scoping are deferred (the service rejects a request needing either before `start` runs). +`{ outputSchema: true, depthLimit: true, toolFilter: false }`. It constructs the child, so it enforces a recursion cap, and it supports structured output via the driver's shared [structured runtime](../subagent-inprocess/README.md) (the backend acquires it for its plugin lifetime; each structured run holds its own acquisition until it settles). Tool-scoping is deferred (the service rejects a request needing it before `start` runs). ## Config | Key | Meaning | |---|---| | `providerName` | Registry name on `ctx.subagents` (default `spawn`). | +| `structuredNudgeRetries` | How many times a structured run re-prompts a child that finished cleanly without calling `structured_output` (default 1). | diff --git a/packages/subagent/subagent-spawn/src/index.ts b/packages/subagent/subagent-spawn/src/index.ts index 2ea082e20a..fdd57fd62a 100644 --- a/packages/subagent/subagent-spawn/src/index.ts +++ b/packages/subagent/subagent-spawn/src/index.ts @@ -9,6 +9,11 @@ * ({@link startInProcessRun}); this backend just passes NO seed (a fresh * child). The fork backend is an independent peer over the same driver. * + * Structured output (`outputSchema`) is supported via the driver's shared + * structured runtime: the backend acquires it for its plugin lifetime (so the + * capture tool and request-shaping listeners exist before any run), and each + * structured run holds its own acquisition until it settles. + * * Plugin export shape: named `name`/`inject`/`Config`/`apply`, NO default. * * @module @deepseek-ai/dsh-subagent-spawn @@ -17,38 +22,61 @@ import type { Context } from 'cordis' import z from 'schemastery' import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } from '@deepseek-ai/dsh-subagent' -import { startInProcessRun } from '@deepseek-ai/dsh-subagent-inprocess' +import { acquireStructuredRuntime, startInProcessRun } from '@deepseek-ai/dsh-subagent-inprocess' export const name = 'subagent-spawn' -export const inject = ['subagents', 'agents'] +export const inject = ['subagents', 'agents', 'tools'] -/** Config: the registry name to register the provider under. */ +/** Config: the registry name to register the provider under, plus structured-run tuning. */ export interface Config { /** Provider name on `ctx.subagents` (default `spawn`). */ providerName: string + /** + * How many times a structured run re-prompts a child that finished cleanly + * without calling `structured_output` before giving up (default 1). + */ + structuredNudgeRetries: number } export const Config: z = z.object({ providerName: z.string().default('spawn'), + structuredNudgeRetries: z.natural().default(1), }) /** * The spawn provider. Supports `depthLimit` (it constructs the child, so it can - * enforce a recursion cap) but NOT `outputSchema` or `toolFilter` in this cut — - * a request that needs either is rejected by the service before `start` runs. + * enforce a recursion cap) and `outputSchema` (via the shared in-process + * structured runtime); NOT `toolFilter` in this cut — a request that needs it + * is rejected by the service before `start` runs. */ class SpawnProvider implements SubagentProvider { - readonly capabilities: SubagentCapabilities = { outputSchema: false, depthLimit: true, toolFilter: false } + readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: false } - constructor(readonly name: string, private readonly ctx: Context) {} + constructor( + readonly name: string, + private readonly ctx: Context, + private readonly structuredNudgeRetries: number, + ) {} start(request: SubagentStartRequest) { // Fresh child: no seed. The shared driver mints ids, stamps cwd/lineage/ - // depth, drives the one-shot, and maps the result. - return startInProcessRun(this.ctx, request, { providerName: this.name }) + // depth, drives the one-shot (including the structured capture/nudge loop + // when the request carries an outputSchema), and maps the result. + return startInProcessRun(this.ctx, request, { + providerName: this.name, + structuredNudgeRetries: this.structuredNudgeRetries, + }) } } export function apply(ctx: Context, config: Config): void { - ctx.subagents.registerProvider(new SpawnProvider(config.providerName, ctx)) + // Hold the structured runtime for the plugin's lifetime, so the capture tool + // and its request-shaping listeners are registered before the first + // structured run and torn down when the last backend unloads (live runs hold + // their own acquisitions, so an unload mid-run cannot strand a child). + ctx.effect(() => { + const acquisition = acquireStructuredRuntime(ctx) + return () => { acquisition.release() } + }, 'subagent-spawn structured runtime') + ctx.subagents.registerProvider(new SpawnProvider(config.providerName, ctx, config.structuredNudgeRetries)) } diff --git a/packages/subagent/subagent-spawn/tests/harness.ts b/packages/subagent/subagent-spawn/tests/harness.ts index ff551cfc3f..cb66a326a6 100644 --- a/packages/subagent/subagent-spawn/tests/harness.ts +++ b/packages/subagent/subagent-spawn/tests/harness.ts @@ -31,7 +31,7 @@ export async function spawnHarness(workdir: string): Promise { await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 }) await ctx.plugin(ToolBash) await ctx.plugin(SubagentService) - await ctx.plugin(Spawn, { providerName: 'spawn' }) + await ctx.plugin(Spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) // The model-facing subagent tool, bound to the spawn backend. await ctx.plugin(ToolSubagent, { provider: 'spawn' }) return ctx diff --git a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts index ccfd6492f4..eaddeae201 100644 --- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts +++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts @@ -34,7 +34,7 @@ async function setup(script: Script) { await ctx.plugin(Invariants) await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SubagentService) - await ctx.plugin(spawn, { providerName: 'spawn' }) + await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) ctx.llm.registerAdapter(['mock'], adapter) const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) return { ctx, parent, adapter } @@ -241,17 +241,21 @@ describe('dsh-subagent-spawn', () => { await parentHandle.dispose() }) - it('advertises depthLimit but not outputSchema/toolFilter', async () => { + it('advertises depthLimit and outputSchema but not toolFilter', async () => { const { ctx } = await setup([]) const provider = ctx.subagents.getProvider('spawn')! - expect(provider.capabilities).toEqual({ outputSchema: false, depthLimit: true, toolFilter: false }) + expect(provider.capabilities).toEqual({ outputSchema: true, depthLimit: true, toolFilter: false }) }) it('unregisters the provider when its fiber is disposed (HMR safety)', async () => { const ctx = new Context() await ctx.plugin(SubagentService) await ctx.plugin(AgentRegistry) - const fiber = await ctx.plugin(spawn, { providerName: 'spawn' }) + // The backend injects 'tools' for the structured runtime, so the registry + // (and its systemPrompt dependency) must be live for the fiber to activate. + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const fiber = await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) expect(ctx.subagents.list()).toEqual(['spawn']) await fiber.dispose() expect(ctx.subagents.list()).toEqual([]) @@ -260,12 +264,12 @@ describe('dsh-subagent-spawn', () => { it('has the namespace-plugin export shape (no stray default)', () => { expect('default' in spawn).toBe(false) expect(spawn.name).toBe('subagent-spawn') - expect(spawn.inject).toEqual(['subagents', 'agents']) + expect(spawn.inject).toEqual(['subagents', 'agents', 'tools']) const loader = Object.create(Loader.prototype) as Loader const unwrapped = loader.unwrapExports(spawn) as Record expect(unwrapped).toBe(spawn) expect(unwrapped.name).toBe('subagent-spawn') - expect(unwrapped.inject).toEqual(['subagents', 'agents']) + expect(unwrapped.inject).toEqual(['subagents', 'agents', 'tools']) expect(typeof unwrapped.apply).toBe('function') }) }) diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts index fb60d5667c..16e6cd5237 100644 --- a/packages/subagent/subagent/src/types.ts +++ b/packages/subagent/subagent/src/types.ts @@ -8,7 +8,7 @@ import type { Agent, AgentId, AgentOptions } from '@deepseek-ai/dsh-agent' import type { ContentBlock } from '@deepseek-ai/dsh-llm' -import type { SchemaSpec } from '@deepseek-ai/dsh-tools' +import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' /** * Which START-TIME features a provider supports. Checked by the service @@ -56,12 +56,16 @@ export interface SubagentStartRequest { /** Per-child agent options (model, system prompt). */ agentOptions?: AgentOptions /** - * Optional structured-output schema. When set AND the provider's - * {@link SubagentCapabilities.outputSchema} is `true`, the child's final - * answer is shaped to this schema and surfaced as {@link SubagentResult.structured}. + * Optional structured-output schema — an object-rooted JSON Schema within the + * enforced subset (see `assertSupportedOutputSchema` in dsh-tools; a schema + * outside the subset is rejected loud at start). When set AND the provider's + * {@link SubagentCapabilities.outputSchema} is `true`, the child is driven to + * report a value matching this schema, surfaced as + * {@link SubagentResult.structured}. The schema must be plain host-realm JSON + * data — a caller holding foreign-realm data materializes it first. * Requesting it against a provider that lacks the capability is rejected at start. */ - outputSchema?: SchemaSpec + outputSchema?: StructuredOutputSchema /** * Optional recursion cap (max delegation depth below this child). Requires * {@link SubagentCapabilities.depthLimit}; rejected at start otherwise. diff --git a/packages/subagent/subagent/tests/service.spec.ts b/packages/subagent/subagent/tests/service.spec.ts index 3a8807ad0d..4e1c5b1bfd 100644 --- a/packages/subagent/subagent/tests/service.spec.ts +++ b/packages/subagent/subagent/tests/service.spec.ts @@ -124,7 +124,7 @@ describe('SubagentService', () => { describe('start-time capability validation (fail loud, before any child)', () => { it.each([ - { field: 'outputSchema', request: baseRequest({ outputSchema: { x: { type: 'string' } } }) }, + { field: 'outputSchema', request: baseRequest({ outputSchema: { type: 'object', properties: { x: { type: 'string' } } } }) }, { field: 'maxDepth', request: baseRequest({ maxDepth: 2 }) }, { field: 'toolFilter', request: baseRequest({ toolFilter: { deny: ['bash'] } }) }, ])('rejects $field against a provider that lacks the capability — before start() runs', ({ request }) => { @@ -149,7 +149,7 @@ describe('SubagentService', () => { await ctx.plugin(SubagentService) const provider = new StubProvider('strong', ALL_CAPS) ctx.subagents.registerProvider(provider) - ctx.subagents.start('strong', baseRequest({ outputSchema: { x: { type: 'string' } }, maxDepth: 1 })) + ctx.subagents.start('strong', baseRequest({ outputSchema: { type: 'object', properties: { x: { type: 'string' } } }, maxDepth: 1 })) expect(provider.startCount).toBe(1) }) }) diff --git a/packages/support/subagent-mock/tests/subagent-mock.spec.ts b/packages/support/subagent-mock/tests/subagent-mock.spec.ts index f35ed884eb..ddd725da4b 100644 --- a/packages/support/subagent-mock/tests/subagent-mock.spec.ts +++ b/packages/support/subagent-mock/tests/subagent-mock.spec.ts @@ -41,13 +41,13 @@ describe('dsh-subagent-mock', () => { it('surfaces a structured result when the request carries an outputSchema', async () => { const ctx = await mount({ reply: 'r', structured: { answer: 42 } }) - const run = ctx.subagents.start('mock', baseRequest({ outputSchema: { answer: { type: 'number' } } })) + const run = ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } })) await expect(run.result).resolves.toMatchObject({ structured: { answer: 42 } }) }) it('defaults structured output to { reply } when outputSchema is requested but no structured value is configured', async () => { const ctx = await mount({ reply: 'fallback reply' }) - const run = ctx.subagents.start('mock', baseRequest({ outputSchema: { answer: { type: 'number' } } })) + const run = ctx.subagents.start('mock', baseRequest({ outputSchema: { type: 'object', properties: { answer: { type: 'number' } } } })) await expect(run.result).resolves.toMatchObject({ structured: { reply: 'fallback reply' } }) }) From 1d43ea3cd5c09880dcbf3fbfbe3b90777a00d094 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 13:29:35 +0800 Subject: [PATCH 004/119] =?UTF-8?q?workflow:=20dynamic=20workflows=20?= =?UTF-8?q?=E2=80=94=20script-driven=20multi-agent=20orchestration?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A new capability family at packages/workflow/ in the bash seam shape, modeled on Claude Code's dynamic workflows: the model writes a JavaScript orchestration script (export const meta = {...} + plain-JS body), a runtime executes it, and the script — not the conversation — holds the loop, the branching, and the intermediate results. - dsh-workflow (ctx.workflows): abstract WorkflowService + run vocabulary (WorkflowRun whose result NEVER rejects) + observe-only workflow/* events carrying data snapshots (id + meta, never the live run), per-listener contained like subagent/*. - dsh-workflow-vm: in-process node:vm engine. Meta extraction via a string/comment-aware scanner (template interpolation rejected; literal evaluated alone in an empty timed context; statement blanked line- preservingly so stacks keep script line numbers). Hooks: agent(prompt, {label, phase, schema, model}) over ctx.subagents, parallel(), pipeline() (no cross-stage barrier), phase(), log(), args. Fatal-vs-null discipline: hook misuse (unknown/deferred options, bad arguments, unsupported schemas, tripped caps, seam start failures, cancellation) throws fatal WorkflowErrors the combinators RE-THROW — never dissolved into the per-item null reserved for child failures. Realm boundary: inbound values materialized by descriptor walks that never invoke accessors (defineProperty copies, __proto__-safe); outbound values rebuilt in-realm via the context's own JSON.parse. Determinism bans (Date.now/Math.random/argless new Date) kept so future resume support cannot break scripts. Caps and timeouts are validated Config. Every hook promise carries a no-op rejection consumer (app-boot exits on unhandled rejections). - dsh-tool-workflow: the model-facing workflow tool, synchronous like dsh-tool-subagent (start → await → try/finally dispose; abort bridged; non-completed → isError). Generic render card titled by a textual meta.name sniff. The tool description carries the authoring contract. Wired into examples/{coding-agent,acp-agent} with explicit-ask-only guidance. Coverage at every tier: unit (meta scanner, materializer incl. counting-getter and __proto__ regressions, combinator semantics, concurrency ceiling, caps, cancellation, no-unhandled-rejection abandon), integration over the real spawn stack, with-key e2e (real two-phase run + the tool through the registry pipeline), and a recorded ACP snapshot scenario (workflow-run, 1 child session). RFC: docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md (deferred work explicitly listed). AGENTS.md budget 1575 → 1590 for the new group's layout line. --- AGENTS.md | 1 + docs/architecture.md | 1 + docs/cordis-catalog/events.md | 62 ++ docs/cordis-catalog/services.md | 16 + docs/core-data-structures/workflow.md | 68 ++ docs/module-graph.md | 16 + docs/rfc/README.md | 1 + .../feature/2026-07-05-dynamic-workflows.md | 58 ++ docs/tool-catalog/tools.md | 39 ++ examples/acp-agent/cordis.yml | 18 + examples/acp-agent/tests/acp.snapshot.ts | 4 + .../tests/snapshots/workflow-run/input.json | 7 + .../snapshots/workflow-run/session.1.jsonl | 37 ++ .../snapshots/workflow-run/session.jsonl | 152 +++++ .../workflow-run/stdout.golden.jsonl | 75 +++ examples/coding-agent/cordis.yml | 20 +- knip.json | 141 +++- packages/README.md | 1 + .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- .../subagent/subagent-inprocess/package.json | 2 + .../tests/structured.spec.ts | 4 +- packages/workflow/README.md | 13 + packages/workflow/tool-workflow/README.md | 22 + packages/workflow/tool-workflow/package.json | 43 ++ packages/workflow/tool-workflow/src/index.ts | 179 +++++ .../tool-workflow/tests/tool-workflow.spec.ts | 224 +++++++ packages/workflow/tool-workflow/tsconfig.json | 33 + packages/workflow/workflow-vm/README.md | 30 + packages/workflow/workflow-vm/package.json | 50 ++ packages/workflow/workflow-vm/src/index.ts | 166 +++++ packages/workflow/workflow-vm/src/meta.ts | 198 ++++++ packages/workflow/workflow-vm/src/realm.ts | 142 ++++ packages/workflow/workflow-vm/src/runtime.ts | 499 ++++++++++++++ .../workflow-vm/tests/integration.spec.ts | 89 +++ .../workflow/workflow-vm/tests/meta.spec.ts | 143 ++++ .../workflow/workflow-vm/tests/realm.spec.ts | 114 ++++ .../workflow-vm/tests/workflow-vm.spec.ts | 614 ++++++++++++++++++ .../workflow-vm/tests/workflow.e2e.ts | 131 ++++ packages/workflow/workflow-vm/tsconfig.json | 39 ++ packages/workflow/workflow/README.md | 29 + packages/workflow/workflow/package.json | 37 ++ packages/workflow/workflow/src/index.ts | 224 +++++++ packages/workflow/workflow/src/types.ts | 154 +++++ .../workflow/workflow/tests/workflow.spec.ts | 86 +++ packages/workflow/workflow/tsconfig.json | 27 + pnpm-lock.yaml | 95 +++ scripts/doc-budgets.manifest.json | 2 +- scripts/gen-tool-catalog.ts | 16 + scripts/type-equiv.manifest.json | 437 ++++++++++--- tsconfig.base.json | 1 + tsconfig.build.json | 3 + tsconfig.json | 3 + 52 files changed, 4459 insertions(+), 109 deletions(-) create mode 100644 docs/core-data-structures/workflow.md create mode 100644 docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md create mode 100644 examples/acp-agent/tests/snapshots/workflow-run/input.json create mode 100644 examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl create mode 100644 examples/acp-agent/tests/snapshots/workflow-run/session.jsonl create mode 100644 examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl create mode 100644 packages/workflow/README.md create mode 100644 packages/workflow/tool-workflow/README.md create mode 100644 packages/workflow/tool-workflow/package.json create mode 100644 packages/workflow/tool-workflow/src/index.ts create mode 100644 packages/workflow/tool-workflow/tests/tool-workflow.spec.ts create mode 100644 packages/workflow/tool-workflow/tsconfig.json create mode 100644 packages/workflow/workflow-vm/README.md create mode 100644 packages/workflow/workflow-vm/package.json create mode 100644 packages/workflow/workflow-vm/src/index.ts create mode 100644 packages/workflow/workflow-vm/src/meta.ts create mode 100644 packages/workflow/workflow-vm/src/realm.ts create mode 100644 packages/workflow/workflow-vm/src/runtime.ts create mode 100644 packages/workflow/workflow-vm/tests/integration.spec.ts create mode 100644 packages/workflow/workflow-vm/tests/meta.spec.ts create mode 100644 packages/workflow/workflow-vm/tests/realm.spec.ts create mode 100644 packages/workflow/workflow-vm/tests/workflow-vm.spec.ts create mode 100644 packages/workflow/workflow-vm/tests/workflow.e2e.ts create mode 100644 packages/workflow/workflow-vm/tsconfig.json create mode 100644 packages/workflow/workflow/README.md create mode 100644 packages/workflow/workflow/package.json create mode 100644 packages/workflow/workflow/src/index.ts create mode 100644 packages/workflow/workflow/src/types.ts create mode 100644 packages/workflow/workflow/tests/workflow.spec.ts create mode 100644 packages/workflow/workflow/tsconfig.json diff --git a/AGENTS.md b/AGENTS.md index ef3526d6fe..f7b750e430 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai web/ web seam + search/fetch providers + model-facing web tools compact/ compaction seam + basic backend subagent/ subagent seam + spawn/fork/ACP backends + delegation tool + workflow/ workflow seam + node:vm script engine + the workflow tool todo/ the todo_write tool hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends diff --git a/docs/architecture.md b/docs/architecture.md index f1f44033a1..47d11d897c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,6 +43,7 @@ Dependency rule: extension plugins depend on interfaces, never on `dsh-agent-loo | `ctx.compact` | dsh-compact | compaction: detect pressure, summarize an older range | | `ctx.web` | dsh-web | search/fetch provider registries + `WebError` taxonomy | | `ctx.subagents` | dsh-subagent | named provider registry for delegating to child agents | +| `ctx.workflows` | dsh-workflow | script-driven multi-agent orchestration: `start()` runs a workflow script | All registrations go through `ctx.effect()` and return disposers, so hot-reload and fiber disposal clean up automatically (full service interfaces: the generated [services catalog](cordis-catalog/services.md)). diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index c85b459069..463c7e06b2 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -313,6 +313,68 @@ Types: [ToolExecution](../core-data-structures/tools.md) Source: [`packages/core/tools/src/index.ts:76`](../../packages/core/tools/src/index.ts) +## `workflow/*` + +### `workflow/agent-end` — emit + +One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start']. + +```ts cordis-catalog +'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void +``` + +Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts) + +### `workflow/agent-start` — emit + +One `agent()` call started a child run. Paired with Events['workflow/agent-end'] by `agent.seq`. + +```ts cordis-catalog +'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void +``` + +Source: [`packages/workflow/workflow/src/index.ts:83`](../../packages/workflow/workflow/src/index.ts) + +### `workflow/end` — emit + +A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start']. + +```ts cordis-catalog +'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void +``` + +Source: [`packages/workflow/workflow/src/index.ts:101`](../../packages/workflow/workflow/src/index.ts) + +### `workflow/log` — emit + +The script emitted a narration line (a `log(message)` call). + +```ts cordis-catalog +'workflow/log'(info: WorkflowRunInfo, message: string): void +``` + +Source: [`packages/workflow/workflow/src/index.ts:75`](../../packages/workflow/workflow/src/index.ts) + +### `workflow/phase` — emit + +The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics. + +```ts cordis-catalog +'workflow/phase'(info: WorkflowRunInfo, title: string): void +``` + +Source: [`packages/workflow/workflow/src/index.ts:68`](../../packages/workflow/workflow/src/index.ts) + +### `workflow/start` — emit + +A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end']. + +```ts cordis-catalog +'workflow/start'(info: WorkflowRunInfo): void +``` + +Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts) + ## Inherited events (cordis core + loader/hmr/timer) The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier's prominence. diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 951e182000..c1f67c0725 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -227,6 +227,22 @@ async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise + cancel(reason?: string): void + dispose(): Promise +} +``` + +## Failure discipline: `WorkflowError.fatal` + +Hook misuse inside a script — bad arguments, unknown/deferred `agent()` options, a schema outside the [structured-output subset](../../packages/core/tools/README.md), a tripped cap, a seam start failure, cancellation — throws a `WorkflowError` with `fatal: true`. The `parallel()`/`pipeline()` combinators RE-THROW fatal errors instead of mapping the item to `null`: a typo'd option must kill the script loudly, never dissolve into something that reads as an ordinary child failure. The per-item `null` is reserved for child-run failures (a non-`completed` stop reason) and ordinary in-stage script errors. + +## Events + +The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](../cordis-catalog/events.md)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — mirroring `subagent/start`/`subagent/end`. diff --git a/docs/module-graph.md b/docs/module-graph.md index e8f1edfaa5..cdb51ef1cc 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -48,6 +48,9 @@ graph TD tools --> agent tools --> llm tools --> system-prompt + workflow --> agent + workflow --> brand + workflow --> llm acp --> agent acp --> llm acp --> session @@ -83,6 +86,10 @@ graph TD tool-web --> system-prompt tool-web --> tools tool-web --> web + tool-workflow --> agent + tool-workflow --> llm + tool-workflow --> tools + tool-workflow --> workflow agent-core --> agent agent-core --> agent-loop agent-core --> invariants @@ -112,6 +119,12 @@ graph TD tool-subagent --> llm tool-subagent --> subagent tool-subagent --> tools + workflow-vm --> agent + workflow-vm --> brand + workflow-vm --> llm + workflow-vm --> subagent + workflow-vm --> tools + workflow-vm --> workflow acp-agent --> acp acp-agent --> agent-core acp-agent --> app-boot @@ -159,6 +172,7 @@ graph TD | `session-persistence-jsonl` | `session`, `session-persistence` | | `session-persistence-sqlite` | `session`, `session-persistence` | | `tools` | `agent`, `llm`, `system-prompt` | +| `workflow` | `agent`, `brand`, `llm` | | `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools` | | `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` | | `hooks-codex` | `agent`, `hook-protocol`, `llm`, `session`, `tools` | @@ -167,12 +181,14 @@ graph TD | `tool-fs` | `fs`, `llm`, `session`, `system-prompt`, `tools` | | `tool-todo` | `agent`, `session`, `tools` | | `tool-web` | `llm`, `system-prompt`, `tools`, `web` | +| `tool-workflow` | `agent`, `llm`, `tools`, `workflow` | | `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` | | `hooks-claude` | `agent`, `hook-protocol`, `llm`, `session`, `subagent`, `tools` | | `subagent-acp` | `agent`, `llm`, `subagent` | | `subagent-inprocess` | `agent`, `llm`, `session`, `subagent`, `tools` | | `subagent-mock` | `agent`, `llm`, `subagent` | | `tool-subagent` | `agent`, `llm`, `subagent`, `tools` | +| `workflow-vm` | `agent`, `brand`, `llm`, `subagent`, `tools`, `workflow` | | `acp-agent` | `acp`, `agent-core`, `app-boot`, `session-persistence-jsonl` | | `stdio-agent` | `agent`, `agent-core`, `app-boot`, `llm`, `session`, `session-persistence-jsonl` | | `subagent-fork` | `agent`, `session`, `subagent`, `subagent-inprocess` | diff --git a/docs/rfc/README.md b/docs/rfc/README.md index 54fdd5de70..12dd2715bd 100644 --- a/docs/rfc/README.md +++ b/docs/rfc/README.md @@ -95,6 +95,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r | [dsh-hook-protocol — the shared Claude Code / Codex hook wire-protocol core](implemented/feature/2026-06-30-hook-protocol-lib.md) | 2026-06-30 | | [Interception seams — the typed-Decision surface a hook programs against](implemented/feature/2026-06-30-interception-seams.md) | 2026-06-30 | | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 | +| [Dynamic workflows — a script-driven multi-agent orchestration seam](implemented/feature/2026-07-05-dynamic-workflows.md) | 2026-07-05 | ### Simplification diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md new file mode 100644 index 0000000000..372fce8f9a --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -0,0 +1,58 @@ +# RFC: Dynamic workflows — a script-driven multi-agent orchestration seam + +- **Status**: implemented +- **Class**: feature +- **First proposed**: 2026-07-05 + +## Problem + +The harness can delegate ONE task to ONE child (`dsh-tool-subagent`), but work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — forces the model to orchestrate turn by turn: every intermediate result lands in the parent context, the plan lives nowhere durable, and coordination costs a model round-trip per step. Claude Code ships this capability as [dynamic workflows](https://code.claude.com/docs/en/workflows): the model writes a JavaScript orchestration script, a runtime executes it, and the script — not the conversation — holds the loop, the branching, and the intermediate results. + +## Proposal + +A workflow capability family at `packages/workflow/` in the bash seam shape (interface / implementation / consumer), plus the structured-output foundation it needs on the subagent seam. + +### The script contract (Claude Code-compatible) + +A script is `export const meta = {...}` (a PURE object literal: `name`, `description`, optional `whenToUse`/`phases`) followed by a plain-JS body with top-level `await`, ending in `return `. The body sees exactly: `agent(prompt, {label, phase, schema, model})`, `parallel(thunks)`, `pipeline(items, ...stages)` (NO cross-stage barrier; `(prev, item, index)` callbacks), `phase(title)`, `log(message)`, and `args`. CC semantics are preserved where they matter to script authors: a failed child resolves `null` (scripts `.filter(Boolean)`); an ordinary stage throw nulls the ITEM and skips its remaining stages; `Date.now()`/`Math.random()`/argless `new Date()` throw (kept banned so future resume support cannot break script compatibility). + +One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferred options (`effort`/`isolation`/`agentType`), malformed arguments, schemas outside the supported subset, tripped caps, seam start failures — throws a `WorkflowError` with `fatal: true`, and the combinators RE-THROW fatal errors instead of nulling the item. Without this, a typo'd option dissolves into a `null` indistinguishable from a child failure — the accepted-then-ignored failure mode this repo bans. One addition: the tool's `args` parameter is a JSON OBJECT (a bare list is wrapped as a field) so the wire schema stays honest. + +### The seam (dsh-workflow) + +`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [core-data-structures/workflow.md](../../../core-data-structures/workflow.md). + +### The engine (dsh-workflow-vm): in-process node:vm + +**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Scripts are model-written — the same trust level as the model's existing bash access — so genuine sandboxing is not the current requirement. The interface/implementation split exists precisely so a hardened engine can swap in later. Accepted, documented limitations: vm is not a security boundary, and the vm timeout covers only the initial synchronous slice — a pathological synchronous spin after the first await cannot be killed in-process; `dispose()` cancels, waits a bounded grace, then abandons. + +**Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. + +**Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm (`args`, `agent()` results) are rebuilt INSIDE the realm via the context's own `JSON.parse`, so the script never holds a live host-prototype object. Realm functions (stages, thunks) are called, never materialized. + +**Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. + +### The consumer (dsh-tool-workflow) + +A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by a textual `meta.name` sniff (presentation is a pure function of args). The tool description IS the model-facing authoring spec. Examples load it with guidance to use workflows only on explicit user request — the harness has no ultracode-style effort gate. + +### The foundation: structured output on the subagent seam + +`agent({schema})` needs `SubagentStartRequest.outputSchema` to actually work; it was vocabulary without an implementation (`outputSchema: false` everywhere). Implemented in `dsh-subagent-inprocess` for both in-process backends: a globally registered `structured_output` capture tool whose per-child schema is enforced by a `prepend: true` `agent/request` listener doing FINAL-REQUEST enforcement (post-processing `await next()` — cooperative mutation would not survive a downstream listener returning a replacement request), an `agent/turn-continuation` veto after capture (no wasted extra model step), validation-retry in-turn via `ToolArgsError`, and a clean-finish nudge loop (`structuredNudgeRetries`). Lifetime is refcounted by backends (plugin lifetime) AND live runs (start → settle). The seam's `outputSchema` type became the raw JSON-Schema SUBSET (`StructuredOutputSchema` in dsh-tools: single-string `type`, `properties`/`required`/`additionalProperties`, `items`, scalar `enum`/`const`; anything unenforced is rejected loud) — the schema travels verbatim to the model as the forced tool's parameters, so the wire format, not the author DSL, is the right vocabulary. + +## What was rejected + +- **Background execution as the default** (CC's shape): deferred; foreground-synchronous matches `dsh-tool-subagent`'s cut, and background semantics should be designed ONCE across bash/subagent/workflow rather than per-tool. +- **Workflow-layer JSON parsing for `agent({schema})`**: duplicating a seam concern at one consumer while the seam's capability flag stayed dishonestly `false`. +- **Meta as tool parameters instead of `export const meta`**: zero parsing, but scripts stop being self-contained artifacts and CC-authored scripts stop being drop-in. +- **`SchemaSpec` as the outputSchema type**: the author-facing DSL cannot express what arrives as data and cannot be validated against without conversion loss. + +## Deferred (documented non-goals of this cut) + +- **Background collection** (start tool → run id → completion notice → collect), designed alongside bash/subagent background unification. +- **Journaling + resume** (`resumeFromRunId`, cached agent() prefixes) — the determinism bans already keep scripts resume-compatible. +- **Saved/bundled workflows** (a `.deepseek/workflows/` registry, slash-command surface) and **script persistence to a run directory** (the tool-call event already records the script durably). +- **Nested `workflow()`**, **token `budget`**, and the `effort`/`isolation`/`agentType` agent options (each rejects loud with a message naming it deferred). +- **Engine hardening**: a worker-thread or isolated-vm engine behind the same seam (kills synchronous spins; adds memory limits). +- **ACP progress UI** over the `workflow/*` events (a `/workflows`-style view); the events exist for it. +- **ACP-backend structured output** and **`toolFilter`** (both still capability-gated `false`). diff --git a/docs/tool-catalog/tools.md b/docs/tool-catalog/tools.md index b1218c3871..9a2d3603f3 100644 --- a/docs/tool-catalog/tools.md +++ b/docs/tool-catalog/tools.md @@ -260,6 +260,45 @@ Record and update a structured task list for the current work. Send the ENTIRE l Source: [`packages/todo/tool-todo/src/index.ts`](../../packages/todo/tool-todo/src/index.ts) +## `@deepseek-ai/dsh-tool-workflow` + +### `workflow` + +Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. + +The script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. + +Script-body hooks: +- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. +- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. +- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. +- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. + +Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. + +Constraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. + +```json +{ + "type": "object", + "properties": { + "script": { + "type": "string", + "description": "The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)." + }, + "args": { + "type": "object", + "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})." + } + }, + "required": [ + "script" + ] +} +``` + +Source: [`packages/workflow/tool-workflow/src/index.ts`](../../packages/workflow/tool-workflow/src/index.ts) + ## `@deepseek-ai/dsh-tool-web` ### `web_fetch` diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml index 01849bb66e..665a6c2071 100644 --- a/examples/acp-agent/cordis.yml +++ b/examples/acp-agent/cordis.yml @@ -56,6 +56,12 @@ subagent_fork instead when the subtask needs THIS conversation's context: the child inherits the log so far. + Use the workflow tool ONLY when the user explicitly asks for a + workflow or for large multi-agent orchestration: you write a + JavaScript script (its description documents the exact format) that + fans work out across many subagents with phases and structured + results. For one or two delegations, prefer plain subagent calls. + For multi-step work, use the todo_write tool to track a task list: send the WHOLE list each call (it replaces the previous one), keep at most one task in_progress (exactly one while work remains), and mark a @@ -93,6 +99,18 @@ provider: fork toolName: subagent_fork + +# Dynamic workflows: the node:vm engine (ctx.workflows) over the spawn subagent +# backend above, plus the model-facing `workflow` tool. The model writes a +# JavaScript orchestration script (meta + body); the engine runs it in-process +# and fans agent() calls out as spawn children. +- id: workflow-vm + name: '@deepseek-ai/dsh-workflow-vm' + config: + provider: spawn + +- id: tool-workflow + name: '@deepseek-ai/dsh-tool-workflow' # The model-facing todo_write tool: whole-list task tracking written to the # session log (todo/write), surfaced to the ACP client as a `plan` update. - id: tool-todo diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 65d2dee9da..5eab642fe4 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -78,6 +78,10 @@ const SCENARIOS: Scenario[] = [ { name: 'subagent-multi', hasModelTurn: true, recorded: true, childSessions: 2 }, { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 }, { name: 'subagent-mixed', hasModelTurn: true, recorded: true, childSessions: 2 }, + // The workflow tool: the model writes a one-child orchestration script; the + // child runs as a spawn subagent inside the vm engine (its session is the + // child fixture), and the tool result carries the script's return value. + { name: 'workflow-run', hasModelTurn: true, recorded: true, childSessions: 1 }, // Hook matrix — one scenario per hook point × its headline Decision outcome, // across BOTH bridges (Claude `hooks.json`, Codex `codex-hooks.json`, seeded in // workspace/). The block scenarios need no model call: a UserPromptSubmit hook diff --git a/examples/acp-agent/tests/snapshots/workflow-run/input.json b/examples/acp-agent/tests/snapshots/workflow-run/input.json new file mode 100644 index 0000000000..2c402dc49e --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workflow-run/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Use the workflow tool exactly once, with args omitted and this EXACT script (copy it verbatim):\nexport const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl new file mode 100644 index 0000000000..de6616fe9b --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl @@ -0,0 +1,37 @@ +{"type":"session","version":0,"id":"d6d69d2a-3933-445f-a84d-d8c1b941f5ce","createdAt":1783227490354,"cwd":"/tmp/acp-snap-cwd-I14oAK","parentSession":"fe74cfdb-40b4-45bd-b6fe-efd2b244c415"} +{"type":"turn/start","seq":0,"time":1783227490354,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783227490354,"data":{"content":[{"type":"text","text":"Reply with exactly the word WF_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783227490355,"data":{"turn":1,"step":1}} +{"type":"assistant/chunk","seq":3,"time":1783227491136,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":4,"time":1783227491137,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":5,"time":1783227491218,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":6,"time":1783227491246,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":7,"time":1783227491247,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":8,"time":1783227491247,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":9,"time":1783227491247,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":10,"time":1783227491247,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":11,"time":1783227491276,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":12,"time":1783227491276,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":13,"time":1783227491276,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} +{"type":"assistant/chunk","seq":14,"time":1783227491304,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":15,"time":1783227491304,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}} +{"type":"assistant/chunk","seq":16,"time":1783227491304,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}} +{"type":"assistant/chunk","seq":17,"time":1783227491304,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}} +{"type":"assistant/chunk","seq":18,"time":1783227491304,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":19,"time":1783227491304,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":20,"time":1783227491336,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":21,"time":1783227491336,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" nothing"}}} +{"type":"assistant/chunk","seq":22,"time":1783227491336,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" else"}}} +{"type":"assistant/chunk","seq":23,"time":1783227491336,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":24,"time":1783227491336,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":25,"time":1783227491336,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"WF"}}} +{"type":"assistant/chunk","seq":26,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_CH"}}} +{"type":"assistant/chunk","seq":27,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ILD"}}} +{"type":"assistant/chunk","seq":28,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} +{"type":"assistant/chunk","seq":29,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"WF_CHILD_OK\" and nothing else."}}}} +{"type":"assistant/chunk","seq":30,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WF_CHILD_OK"}}}} +{"type":"assistant/chunk","seq":31,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2707,"outputTokens":25,"cacheReadTokens":0,"reasoningTokens":20}}}} +{"type":"assistant/chunk","seq":32,"time":1783227491366,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":33,"time":1783227491366,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"WF_CHILD_OK\" and nothing else."},{"type":"text","text":"WF_CHILD_OK"}],"usage":{"inputTokens":2707,"outputTokens":25,"cacheReadTokens":0,"reasoningTokens":20}},"sourceEventSeqs":[3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32],"surfaceOp":"append"} +{"type":"step/end","seq":34,"time":1783227491367,"data":{"turn":1,"step":1}} +{"type":"turn/end","seq":35,"time":1783227491367,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl new file mode 100644 index 0000000000..9509032af2 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl @@ -0,0 +1,152 @@ +{"type":"session","version":0,"id":"fe74cfdb-40b4-45bd-b6fe-efd2b244c415","createdAt":1783227488560,"cwd":"/tmp/acp-snap-cwd-I14oAK"} +{"type":"turn/start","seq":0,"time":1783227488563,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783227488564,"data":{"content":[{"type":"text","text":"Use the workflow tool exactly once, with args omitted and this EXACT script (copy it verbatim):\nexport const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783227488565,"data":{"turn":1,"step":1}} +{"type":"assistant/chunk","seq":3,"time":1783227489485,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":4,"time":1783227489486,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":5,"time":1783227489604,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":6,"time":1783227489638,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":7,"time":1783227489639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":8,"time":1783227489639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":9,"time":1783227489639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":10,"time":1783227489665,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":11,"time":1783227489665,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}} +{"type":"assistant/chunk","seq":12,"time":1783227489666,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} +{"type":"assistant/chunk","seq":13,"time":1783227489666,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":14,"time":1783227489692,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":15,"time":1783227489693,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exact"}}} +{"type":"assistant/chunk","seq":16,"time":1783227489693,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" script"}}} +{"type":"assistant/chunk","seq":17,"time":1783227489693,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" provided"}}} +{"type":"assistant/chunk","seq":18,"time":1783227489720,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}} +{"type":"assistant/chunk","seq":19,"time":1783227489720,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" args"}}} +{"type":"assistant/chunk","seq":20,"time":1783227489774,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" omitted"}}} +{"type":"assistant/chunk","seq":21,"time":1783227489775,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}} +{"type":"assistant/chunk","seq":22,"time":1783227489775,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":23,"time":1783227489775,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}} +{"type":"assistant/chunk","seq":24,"time":1783227489781,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":25,"time":1783227489781,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":26,"time":1783227489811,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":27,"time":1783227489811,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WORK"}}} +{"type":"assistant/chunk","seq":28,"time":1783227489811,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}} +{"type":"assistant/chunk","seq":29,"time":1783227489811,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}} +{"type":"assistant/chunk","seq":30,"time":1783227489841,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}} +{"type":"assistant/chunk","seq":31,"time":1783227489841,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":32,"time":1783227489842,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":33,"time":1783227489842,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" after"}}} +{"type":"assistant/chunk","seq":34,"time":1783227489842,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}} +{"type":"assistant/chunk","seq":35,"time":1783227489869,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} +{"type":"assistant/chunk","seq":36,"time":1783227489869,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":37,"time":1783227489961,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":38,"time":1783227489961,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":39,"time":1783227489961,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":40,"time":1783227489961,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":41,"time":1783227489991,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"script"}}} +{"type":"assistant/chunk","seq":42,"time":1783227489991,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":43,"time":1783227489991,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":44,"time":1783227489991,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":45,"time":1783227490021,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"export"}}} +{"type":"assistant/chunk","seq":46,"time":1783227490021,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" const"}}} +{"type":"assistant/chunk","seq":47,"time":1783227490021,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" meta"}}} +{"type":"assistant/chunk","seq":48,"time":1783227490021,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":49,"time":1783227490021,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" {"}}} +{"type":"assistant/chunk","seq":50,"time":1783227490021,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" name"}}} +{"type":"assistant/chunk","seq":51,"time":1783227490049,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":52,"time":1783227490049,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" '"}}} +{"type":"assistant/chunk","seq":53,"time":1783227490050,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"sn"}}} +{"type":"assistant/chunk","seq":54,"time":1783227490050,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"apshot"}}} +{"type":"assistant/chunk","seq":55,"time":1783227490050,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"-flow"}}} +{"type":"assistant/chunk","seq":56,"time":1783227490050,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"',"}}} +{"type":"assistant/chunk","seq":57,"time":1783227490078,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":58,"time":1783227490078,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":59,"time":1783227490078,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" '"}}} +{"type":"assistant/chunk","seq":60,"time":1783227490078,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"one"}}} +{"type":"assistant/chunk","seq":61,"time":1783227490078,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" child"}}} +{"type":"assistant/chunk","seq":62,"time":1783227490107,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" for"}}} +{"type":"assistant/chunk","seq":63,"time":1783227490108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" the"}}} +{"type":"assistant/chunk","seq":64,"time":1783227490108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" snapshot"}}} +{"type":"assistant/chunk","seq":65,"time":1783227490108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"'"}}} +{"type":"assistant/chunk","seq":66,"time":1783227490108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" }\\n"}}} +{"type":"assistant/chunk","seq":67,"time":1783227490108,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"phase"}}} +{"type":"assistant/chunk","seq":68,"time":1783227490137,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"('"}}} +{"type":"assistant/chunk","seq":69,"time":1783227490137,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"Run"}}} +{"type":"assistant/chunk","seq":70,"time":1783227490137,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"')\\n"}}} +{"type":"assistant/chunk","seq":71,"time":1783227490137,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":72,"time":1783227490137,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" reply"}}} +{"type":"assistant/chunk","seq":73,"time":1783227490166,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":74,"time":1783227490166,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":75,"time":1783227490166,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" agent"}}} +{"type":"assistant/chunk","seq":76,"time":1783227490166,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"('"}}} +{"type":"assistant/chunk","seq":77,"time":1783227490196,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"Reply"}}} +{"type":"assistant/chunk","seq":78,"time":1783227490196,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" with"}}} +{"type":"assistant/chunk","seq":79,"time":1783227490196,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" exactly"}}} +{"type":"assistant/chunk","seq":80,"time":1783227490196,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" the"}}} +{"type":"assistant/chunk","seq":81,"time":1783227490224,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" word"}}} +{"type":"assistant/chunk","seq":82,"time":1783227490224,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" WF"}}} +{"type":"assistant/chunk","seq":83,"time":1783227490225,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"_CH"}}} +{"type":"assistant/chunk","seq":84,"time":1783227490225,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"ILD"}}} +{"type":"assistant/chunk","seq":85,"time":1783227490225,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":86,"time":1783227490253,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" and"}}} +{"type":"assistant/chunk","seq":87,"time":1783227490253,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" nothing"}}} +{"type":"assistant/chunk","seq":88,"time":1783227490253,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" else"}}} +{"type":"assistant/chunk","seq":89,"time":1783227490253,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":".')\\n"}}} +{"type":"assistant/chunk","seq":90,"time":1783227490253,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":91,"time":1783227490253,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" {"}}} +{"type":"assistant/chunk","seq":92,"time":1783227490278,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" reply"}}} +{"type":"assistant/chunk","seq":93,"time":1783227490279,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":" }"}}} +{"type":"assistant/chunk","seq":94,"time":1783227490279,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":95,"time":1783227490314,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":96,"time":1783227490347,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run the workflow tool with the exact script provided, args omitted, and then reply with \"WORKFLOW_DONE\" after it returns."}}}} +{"type":"assistant/chunk","seq":97,"time":1783227490347,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","arguments":"{\"script\": \"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\"}"}}}} +{"type":"assistant/chunk","seq":98,"time":1783227490347,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3124,"outputTokens":125,"cacheReadTokens":0,"reasoningTokens":33}}}} +{"type":"assistant/chunk","seq":99,"time":1783227490347,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":100,"time":1783227490349,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run the workflow tool with the exact script provided, args omitted, and then reply with \"WORKFLOW_DONE\" after it returns."},{"type":"tool-call","id":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","arguments":"{\"script\": \"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\"}"}],"usage":{"inputTokens":3124,"outputTokens":125,"cacheReadTokens":0,"reasoningTokens":33}},"sourceEventSeqs":[3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99],"surfaceOp":"append"} +{"type":"tool/call","seq":101,"time":1783227490349,"data":{"turn":1,"step":1,"callId":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","name":"workflow","arguments":"{\"script\": \"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\"}"}} +{"type":"tool/result","seq":102,"time":1783227491372,"data":{"turn":1,"step":1,"callId":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","content":[{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WF_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[101],"surfaceOp":"append"} +{"type":"step/end","seq":103,"time":1783227491373,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":104,"time":1783227491373,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":105,"time":1783227491987,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":106,"time":1783227491988,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":107,"time":1783227492202,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}} +{"type":"assistant/chunk","seq":108,"time":1783227492230,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" returned"}}} +{"type":"assistant/chunk","seq":109,"time":1783227492231,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}} +{"type":"assistant/chunk","seq":110,"time":1783227492231,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":111,"time":1783227492259,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":112,"time":1783227492260,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":113,"time":1783227492287,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":114,"time":1783227492288,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}} +{"type":"assistant/chunk","seq":115,"time":1783227492288,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}} +{"type":"assistant/chunk","seq":116,"time":1783227492288,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}} +{"type":"assistant/chunk","seq":117,"time":1783227492288,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":118,"time":1783227492288,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":119,"time":1783227492317,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Now"}}} +{"type":"assistant/chunk","seq":120,"time":1783227492317,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":121,"time":1783227492317,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} +{"type":"assistant/chunk","seq":122,"time":1783227492317,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":123,"time":1783227492317,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":124,"time":1783227492345,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":125,"time":1783227492345,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":126,"time":1783227492374,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":127,"time":1783227492374,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} +{"type":"assistant/chunk","seq":128,"time":1783227492374,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":129,"time":1783227492374,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WORK"}}} +{"type":"assistant/chunk","seq":130,"time":1783227492374,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}} +{"type":"assistant/chunk","seq":131,"time":1783227492374,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}} +{"type":"assistant/chunk","seq":132,"time":1783227492411,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}} +{"type":"assistant/chunk","seq":133,"time":1783227492412,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":134,"time":1783227492412,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":135,"time":1783227492435,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":136,"time":1783227492435,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":137,"time":1783227492435,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":138,"time":1783227492435,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":139,"time":1783227492435,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WORK"}}} +{"type":"assistant/chunk","seq":140,"time":1783227492435,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"FL"}}} +{"type":"assistant/chunk","seq":141,"time":1783227492464,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OW"}}} +{"type":"assistant/chunk","seq":142,"time":1783227492464,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_D"}}} +{"type":"assistant/chunk","seq":143,"time":1783227492464,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":144,"time":1783227492465,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with the single word \"WORKFLOW_DONE\" and stop."}}}} +{"type":"assistant/chunk","seq":145,"time":1783227492465,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WORKFLOW_DONE"}}}} +{"type":"assistant/chunk","seq":146,"time":1783227492465,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":87,"outputTokens":38,"cacheReadTokens":3200,"reasoningTokens":32}}}} +{"type":"assistant/chunk","seq":147,"time":1783227492465,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":148,"time":1783227492465,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with the single word \"WORKFLOW_DONE\" and stop."},{"type":"text","text":"WORKFLOW_DONE"}],"usage":{"inputTokens":87,"outputTokens":38,"cacheReadTokens":3200,"reasoningTokens":32}},"sourceEventSeqs":[105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147],"surfaceOp":"append"} +{"type":"step/end","seq":149,"time":1783227492465,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":150,"time":1783227492465,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl new file mode 100644 index 0000000000..6955ea7cc8 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl @@ -0,0 +1,75 @@ +{"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}}"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" workflow"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exact"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" script"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" provided"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" args"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" omitted"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" then"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WORK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"FL"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OW"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" after"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","title":"workflow: snapshot-flow","kind":"other","status":"in_progress","rawInput":"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_OvqFfefZ8c0hnuo9Eq9f8866","status":"completed","content":[{"type":"content","content":{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WF_CHILD_OK\"\n}"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" workflow"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returned"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" successfully"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WF"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_CH"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ILD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WORK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"FL"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OW"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"WORK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"FL"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"OW"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml index 0c95299fca..f6f56cb57d 100644 --- a/examples/coding-agent/cordis.yml +++ b/examples/coding-agent/cordis.yml @@ -46,7 +46,7 @@ # under ./.sessions); unset starts a fresh session each run. resumeSessionId: !!js process.env.RESUME_SESSION_ID persistenceRoot: './.sessions' - welcome: 'agent REPL ready. Give it a coding task (its tools are read, write, edit, bash, subagent, and todo_write).' + welcome: 'agent REPL ready. Give it a coding task (its tools are read, write, edit, bash, subagent, workflow, and todo_write).' systemPrompt: | You are coding-agent, a CLI coding assistant. @@ -64,6 +64,12 @@ subagent_fork instead when the subtask needs THIS conversation's context: the child inherits the log so far. + Use the workflow tool ONLY when the user explicitly asks for a + workflow or for large multi-agent orchestration: you write a + JavaScript script (its description documents the exact format) that + fans work out across many subagents with phases and structured + results. For one or two delegations, prefer plain subagent calls. + Check the [exit code: N] marker on every command; investigate failures before moving on. Verify your work by running the code or tests. Keep answers brief and factual. @@ -120,6 +126,18 @@ provider: fork toolName: subagent_fork + +# Dynamic workflows: the node:vm engine (ctx.workflows) over the spawn subagent +# backend above, plus the model-facing `workflow` tool. The model writes a +# JavaScript orchestration script (meta + body); the engine runs it in-process +# and fans agent() calls out as spawn children. +- id: workflow-vm + name: '@deepseek-ai/dsh-workflow-vm' + config: + provider: spawn + +- id: tool-workflow + name: '@deepseek-ai/dsh-tool-workflow' # The model-facing todo_write tool: whole-list task tracking written to the # session log (todo/write), rendered as a stdio checklist / ACP plan. - id: tool-todo diff --git a/knip.json b/knip.json index 5e61645458..39fb4c414f 100644 --- a/knip.json +++ b/knip.json @@ -1,7 +1,11 @@ { "$schema": "https://unpkg.com/knip@5/schema.json", - "exclude": ["duplicates"], - "ignoreWorkspaces": ["vendor/*"], + "exclude": [ + "duplicates" + ], + "ignoreWorkspaces": [ + "vendor/*" + ], "workspaces": { ".": { "entry": [ @@ -11,55 +15,138 @@ "examples/acp-agent/tests/**/*.e2e.ts", "examples/acp-agent/tests/**/*.snapshot.ts" ], - "project": ["scripts/**/*.ts", "examples/**/*.ts"] + "project": [ + "scripts/**/*.ts", + "examples/**/*.ts" + ] }, "packages/*/*": { - "entry": ["tests/**/*.spec.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/util/brand": { - "project": ["src/**/*.ts"], - "ignoreDependencies": ["cordis"] + "project": [ + "src/**/*.ts" + ], + "ignoreDependencies": [ + "cordis" + ] }, "packages/llm/llm-deepseek": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/llm/llm-pi-ai": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/web/web-search-exa": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/web/web-search-perplexity": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/web/web-search-deepseek": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/ui/acp-agent": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/ui/stdio-agent": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/subagent/subagent-spawn": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/subagent/subagent-acp": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/mock-acp-server.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts", + "tests/mock-acp-server.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] }, "packages/fs/tool-fs": { - "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"] + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] + }, + "packages/workflow/workflow-vm": { + "entry": [ + "tests/**/*.spec.ts", + "tests/**/*.e2e.ts" + ], + "project": [ + "src/**/*.ts", + "tests/**/*.ts" + ] } } } diff --git a/packages/README.md b/packages/README.md index f07e0d5a36..3c38eda671 100644 --- a/packages/README.md +++ b/packages/README.md @@ -14,6 +14,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface | | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | +| [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the node:vm engine, and the model-facing `workflow` tool | Product — stable surface | | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index 05236dd322..874f697797 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { it('boots every shipped tool package and harvests its model-facing schemas', async () => { const catalog = await collectToolCatalog() const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort() - expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) + expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write']) // Every tool carries a JSON-Schema `parameters` object (what the model sees). for (const entry of catalog) { for (const schema of entry.schemas) { diff --git a/packages/subagent/subagent-inprocess/package.json b/packages/subagent/subagent-inprocess/package.json index 41c46e00d3..9a53dd61f4 100644 --- a/packages/subagent/subagent-inprocess/package.json +++ b/packages/subagent/subagent-inprocess/package.json @@ -36,6 +36,8 @@ "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", + "@deepseek-ai/dsh-subagent-fork": "workspace:^", + "@deepseek-ai/dsh-subagent-spawn": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "cordis": "^4.0.0-rc.6" diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts index 643000de2c..0a92c15fa8 100644 --- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts @@ -10,8 +10,8 @@ import * as Invariants from '@deepseek-ai/dsh-invariants' import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent' import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' -import * as spawn from '../../subagent-spawn/src/index.ts' -import * as fork from '../../subagent-fork/src/index.ts' +import * as spawn from '@deepseek-ai/dsh-subagent-spawn' +import * as fork from '@deepseek-ai/dsh-subagent-fork' import { acquireStructuredRuntime, STRUCTURED_OUTPUT_INSTRUCTION, diff --git a/packages/workflow/README.md b/packages/workflow/README.md new file mode 100644 index 0000000000..f28a325ea8 --- /dev/null +++ b/packages/workflow/README.md @@ -0,0 +1,13 @@ +# workflow/ — dynamic-workflow capability family + +The workflow seam: a model-written JavaScript orchestration script that fans out subagents at scale (phases, structured per-agent results, concurrency caps), modeled on Claude Code's dynamic workflows. A capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)) in the bash shape: ONE engine implementation per context registers as `ctx.workflows`; the model-facing tool consumes it. + +| Package | Role | ctx key | +|---|---|---| +| `workflow/` | Abstract workflow seam: service base class + run vocabulary + `workflow/*` events | `ctx.workflows` | +| `workflow-vm/` | In-process `node:vm` engine: parses the script, injects the hooks, drives `ctx.subagents` | (provides `ctx.workflows`) | +| `tool-workflow/` | Model-facing `workflow` tool over `ctx.workflows` | (registers on `ctx.tools`) | + +The interface lives at `workflow/workflow/`. The engine's `agent()` hook rides the [subagent seam](../subagent/README.md) (any registered provider; the shipped examples use `spawn`), and `agent({ schema })` rides the structured-output support the in-process backends implement. The seam split exists for engine hardening: `node:vm` is in-process and cannot kill a pathological synchronous spin — a worker-thread or isolated-vm engine swaps in behind the same interface if that ever matters. + +The proposal, decisions, and deferred work: [docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md](../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md). diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md new file mode 100644 index 0000000000..4cd86fb43b --- /dev/null +++ b/packages/workflow/tool-workflow/README.md @@ -0,0 +1,22 @@ +# @deepseek-ai/dsh-tool-workflow + +The model-facing **`workflow` tool**: run a JavaScript orchestration script that fans out subagents, and return the script's final value. Pure schema + lifecycle shaping over [`ctx.workflows`](../workflow/README.md) — script parsing, execution, caps, and cancellation live behind the seam, so a hardened engine swaps in without touching what the model sees. + +## What the model sees + +Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, determinism bans, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). + +## Lifecycle + +Collection is SYNCHRONOUS this cut (like [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)): `execute` starts a run and awaits `run.result` inside a `try/finally` that always disposes the run, so the script and its children reach quiescence on every path. `exec.signal` is bridged to `run.cancel()` (including the already-aborted-before-start case). A non-`completed` stop reason maps to an `isError` result reporting the reason — never partial output as success; a parse/meta failure thrown synchronously by `start()` becomes an `isError` the model can correct from. The completed result renders the meta name, the agent count, and the return value as JSON, truncated at `maxResultChars` with an explicit notice. + +## Render intent + +Decided up front (per the [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md)): a `generic` card titled `workflow: `, the name sniffed TEXTUALLY from `args.script` (presentation must be a pure function of args, so it cannot ask the engine to parse); the script text rides as `rawInput`. The result keeps the generic card. + +## Config + +| Key | Default | Meaning | +|---|---|---| +| `toolName` | `workflow` | The model-facing tool name to register. | +| `maxResultChars` | `50000` | Rendered-result ceiling; longer JSON is truncated with a notice. | diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json new file mode 100644 index 0000000000..9c3f819cb5 --- /dev/null +++ b/packages/workflow/tool-workflow/package.json @@ -0,0 +1,43 @@ +{ + "name": "@deepseek-ai/dsh-tool-workflow", + "description": "Model-facing workflow tool: run a JavaScript orchestration script over ctx.workflows", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "@deepseek-ai/dsh-workflow": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "@deepseek-ai/dsh-workflow": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts new file mode 100644 index 0000000000..eeed5c9dbe --- /dev/null +++ b/packages/workflow/tool-workflow/src/index.ts @@ -0,0 +1,179 @@ +/** + * The model-facing `workflow` tool: run a JavaScript orchestration script that + * fans out subagents, and return the script's final value. Pure schema + + * lifecycle shaping — script parsing, execution, caps, and cancellation live + * behind `ctx.workflows` (`@deepseek-ai/dsh-workflow`), so a hardened engine + * swaps in without touching what the model sees. + * + * Collection is SYNCHRONOUS this cut (like `dsh-tool-subagent`): `execute` + * starts a run and awaits `run.result` inside a `try/finally` that always + * disposes the run, so the script and its children are torn down on every + * path. A non-`completed` stop reason maps to an `isError` tool result (by + * throwing) rather than returning partial output as success. Background + * collection is deferred to the cross-tool background redesign. + * + * Render intent (decided up front, per the render-intent RFC): a `generic` + * card whose title carries the script's `meta.name`, sniffed textually from + * the args — presentation must be a pure function of `args`, so it cannot ask + * the engine to parse. + * + * @module @deepseek-ai/dsh-tool-workflow + */ + +import type { Context } from 'cordis' +import z from 'schemastery' +import { defineTool } from '@deepseek-ai/dsh-tools' +import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { WorkflowResult, WorkflowRun } from '@deepseek-ai/dsh-workflow' + +export const name = 'tool-workflow' +export const inject = ['tools', 'workflows'] + +/** Config: the model-facing tool name plus result rendering caps. */ +export interface Config { + /** The model-facing tool name to register (default `workflow`). */ + toolName?: string + /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */ + maxResultChars?: number +} + +export const Config: z = z.object({ + toolName: z.string().default('workflow'), + maxResultChars: z.natural().min(1).default(50_000), +}) + +/** + * The script-authoring contract, embedded in the tool description. This IS the + * model-facing spec: the meta block, the hooks and their exact semantics, the + * determinism bans, and the supported schema subset. + */ +const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. + +The script MUST begin with \`export const meta = {...}\` — a PURE object literal (no variables, calls, or template interpolation) with required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, model?}\`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with \`return \` — the value must be JSON-serializable and is this tool's result. + +Script-body hooks: +- \`agent(prompt, opts?): Promise\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), \`model\` (override). Anything else (\`effort\`/\`isolation\`/\`agentType\`) is rejected loudly. +- \`pipeline(items, ...stages): Promise\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. An ordinary stage throw drops that ITEM to \`null\` and skips its remaining stages. +- \`parallel(thunks): Promise\` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to \`null\`. +- \`phase(title)\` — start a progress phase; \`log(message)\` — narrate progress; \`args\` — the tool call's \`args\` input, verbatim. + +Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`. + +Constraints: concurrency and total-agent caps apply; \`Date.now()\`, \`Math.random()\`, and argless \`new Date()\` throw (pass timestamps via \`args\`); no filesystem, network, timers, or Node.js APIs — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.` + +type WorkflowCallArgs = { script: string; args?: Record } + +/** Best-effort meta.name sniff for presentation (pure textual; no evaluation). */ +function sniffMetaName(script: string): string | undefined { + const match = /export\s+const\s+meta\s*=\s*\{[^{}]*?name\s*:\s*(['"`])([^'"`\n]{1,64})\1/.exec(script) + return match?.[2] +} + +/** The pending-state card: a generic card titled by the script's meta name. */ +function presentWorkflowCall(args: WorkflowCallArgs): ToolCallView { + const name = sniffMetaName(args.script) + return { + card: 'generic', + title: name !== undefined ? `workflow: ${name}` : 'workflow', + rawInput: args.script, + } +} + +/** The completed-state card: keep the pending title; render the result content as-is. */ +function presentWorkflowResult(args: WorkflowCallArgs, result: { content: ContentBlock[]; isError: boolean }): ToolResultView { + void args + void result + return { card: 'generic' } +} + +/** A non-`completed` stop reason means the script did not finish cleanly. */ +function stopReasonError(result: WorkflowResult): string | undefined { + switch (result.stopReason) { + case 'completed': + return undefined + case 'cancelled': + return `workflow run was cancelled${result.error !== undefined ? ` (${result.error})` : ''}` + case 'error': + return `workflow run failed: ${result.error ?? 'unknown error'}` + /* v8 ignore start -- defensive: WorkflowStopReason is a closed union, exhaustive by construction; a future variant fails here loudly */ + default: + return `workflow run ended abnormally (${String(result.stopReason satisfies never)})` + /* v8 ignore stop */ + } +} + +/** Render the run's outcome text: the meta name, agent count, and the JSON value (capped). */ +function renderResult(run: WorkflowRun, result: WorkflowResult, maxChars: number): string { + // The engine returns JSON data (null for a valueless script), so stringify never yields undefined. + const rendered = JSON.stringify(result.value, null, 2) + const clipped = rendered.length > maxChars + ? `${rendered.slice(0, maxChars)}\n… [truncated: ${rendered.length - maxChars} more characters]` + : rendered + return `workflow "${run.meta.name}" completed (${result.agentsStarted} agent${result.agentsStarted === 1 ? '' : 's'}).\nReturn value:\n${clipped}` +} + +export function apply(ctx: Context, config: Config): void { + const maxResultChars = config.maxResultChars ?? 50_000 + ctx.tools.register(defineTool({ + name: config.toolName ?? 'workflow', + description: DESCRIPTION, + parameters: { + script: { + type: 'string', + required: true, + description: 'The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `).', + }, + args: { + type: 'object', + description: 'Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}).', + }, + }, + async execute(args, exec): Promise { + const parent = exec.agent + if (!parent) { + // The loop sets `exec.agent` for every model-driven call; its absence + // means a non-agent caller invoked the tool directly, which has no + // parent to attribute the children to. Fail loud rather than guess. + throw new Error('workflow tool requires a calling agent (exec.agent was undefined)') + } + + // Parse failures (SCRIPT_PARSE/META_INVALID) throw synchronously here + // and become isError results via the registry — the model sees the + // violation list and can correct the script. + const run: WorkflowRun = ctx.workflows.start({ + script: args.script, + ...args.args !== undefined ? { args: args.args } : {}, + parent, + ...exec.signal ? { signal: exec.signal } : {}, + }) + + // Bridge the tool's abort signal to the run: if the parent step is + // aborted while the script is in flight, cancel the whole run. The + // engine also receives `signal` directly, but an explicit bridge keeps + // the tool's contract local (and covers an engine that ignores it). + const onAbort = (): void => { run.cancel('parent step aborted') } + exec.signal?.addEventListener('abort', onAbort, { once: true }) + // `addEventListener` does NOT fire for a signal already aborted before + // this line — cancel explicitly in that case. + if (exec.signal?.aborted) run.cancel('parent step aborted') + + try { + const result = await run.result + const error = stopReasonError(result) + if (error !== undefined) { + // Map a non-clean finish to an isError result (the registry turns a + // throw into an isError). Report the reason, not partial output. + throw new Error(error) + } + return [{ type: 'text', text: renderResult(run, result, maxResultChars) }] + } finally { + exec.signal?.removeEventListener('abort', onAbort) + // Always reach run quiescence — never leak a live script or children. + await run.dispose() + } + }, + presentCall: args => presentWorkflowCall(args), + presentResult: (args, result) => presentWorkflowResult(args, result), + })) +} diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts new file mode 100644 index 0000000000..012fae4961 --- /dev/null +++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts @@ -0,0 +1,224 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools' +import { AgentId } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { WorkflowRunId, WorkflowService } from '@deepseek-ai/dsh-workflow' +import type { WorkflowResult, WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' +import { CallId } from '@deepseek-ai/dsh-llm' +import * as toolWorkflow from '../src/index.ts' + +/** A controllable engine standing in behind ctx.workflows (the tool's only seam). */ +class StubEngine extends WorkflowService { + requests: WorkflowStartRequest[] = [] + cancels: string[] = [] + disposed = 0 + settle!: (result: WorkflowResult) => void + startError: Error | undefined + + start(request: WorkflowStartRequest): WorkflowRun { + if (this.startError) throw this.startError + this.requests.push(request) + const result = new Promise((resolve) => { this.settle = resolve }) + request.signal?.addEventListener('abort', () => { + this.settle({ value: null, stopReason: 'cancelled', error: 'signal', agentsStarted: 0 }) + }, { once: true }) + return { + id: WorkflowRunId('run-1'), + meta: { name: 'stub-flow', description: 'd' }, + result, + cancel: (reason?: string) => { + this.cancels.push(reason ?? 'cancelled') + this.settle({ value: null, stopReason: 'cancelled', ...reason !== undefined ? { error: reason } : {}, agentsStarted: 0 }) + }, + dispose: () => { + this.disposed += 1 + return Promise.resolve() + }, + } + } +} + +async function setup(config?: { toolName?: string; maxResultChars?: number }) { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(StubEngine) + await ctx.plugin(toolWorkflow, config ?? {}) + const engine = ctx.workflows as StubEngine + const parent = { id: AgentId('caller'), options: {} } as unknown as Agent + return { ctx, engine, parent } +} + +const SCRIPT = "export const meta = { name: 'audit', description: 'd' }\nreturn 1" + +function execute(ctx: Context, args: unknown, extra?: { agent?: Agent; signal?: AbortSignal }): Promise { + return ctx.tools.execute({ + callId: CallId('call-1'), + name: 'workflow', + arguments: args, + ...extra?.agent ? { agent: extra.agent } : {}, + ...extra?.signal ? { signal: extra.signal } : {}, + }) +} + +describe('dsh-tool-workflow', () => { + it('starts a run with the script/args/parent/signal and renders the completed value', async () => { + const { ctx, engine, parent } = await setup() + const controller = new AbortController() + const pending = execute(ctx, { script: SCRIPT, args: { files: ['a.ts'] } }, { agent: parent, signal: controller.signal }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) + expect(engine.requests[0]).toMatchObject({ script: SCRIPT, args: { files: ['a.ts'] }, parent }) + expect(engine.requests[0]!.signal).toBe(controller.signal) + engine.settle({ value: { findings: [1, 2] }, stopReason: 'completed', agentsStarted: 7 }) + const result = await pending + expect(result.isError).toBe(false) + const rendered = (result.content[0] as { text: string }).text + expect(rendered).toContain('workflow "stub-flow" completed (7 agents)') + expect(rendered).toContain('"findings"') + expect(engine.disposed).toBe(1) + }) + + it('maps a non-completed stop reason to an isError result (and still disposes)', async () => { + const { ctx, engine, parent } = await setup() + const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) + engine.settle({ value: null, stopReason: 'error', error: 'script threw: boom', agentsStarted: 2 }) + const result = await pending + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('workflow run failed: script threw: boom') + expect(engine.disposed).toBe(1) + }) + + it('reports a cancelled run distinctly (with and without a reason)', async () => { + const { ctx, engine, parent } = await setup() + const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) + engine.settle({ value: null, stopReason: 'cancelled', error: 'user', agentsStarted: 0 }) + const result = await pending + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('workflow run was cancelled (user)') + + const bare = execute(ctx, { script: SCRIPT }, { agent: parent }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(2) }) + engine.settle({ value: null, stopReason: 'cancelled', agentsStarted: 0 }) + expect(((await bare).content[0] as { text: string }).text.trim().endsWith('cancelled')).toBe(true) + }) + + it('an error result without a message renders the unknown-error fallback', async () => { + const { ctx, engine, parent } = await setup() + const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) + engine.settle({ value: null, stopReason: 'error', agentsStarted: 0 }) + expect(((await pending).content[0] as { text: string }).text).toContain('unknown error') + }) + + it('cancels the run when exec.signal aborts MID-FLIGHT (the abort bridge)', async () => { + const { ctx, engine, parent } = await setup() + const controller = new AbortController() + const pending = execute(ctx, { script: SCRIPT }, { agent: parent, signal: controller.signal }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) + controller.abort() + const result = await pending + expect(result.isError).toBe(true) + expect(engine.cancels).toContain('parent step aborted') + expect(engine.disposed).toBe(1) + }) + + it('applies raw-config fallbacks when loaded without schemastery defaults (direct apply)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(StubEngine) + // Direct apply with an empty RAW config: the `??` fallbacks resolve the + // tool name and render cap without schemastery having filled them. + toolWorkflow.apply(ctx, {}) + expect(ctx.tools.get('workflow')).toBeDefined() + }) + + it('a synchronous engine start throw (parse/meta failure) becomes an isError result', async () => { + const { ctx, engine, parent } = await setup() + engine.startError = new Error('script must begin with `export const meta = {...}`') + const result = await execute(ctx, { script: 'nope' }, { agent: parent }) + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('must begin with') + }) + + it('requires a calling agent (fails loud without exec.agent)', async () => { + const { ctx, engine } = await setup() + const result = await execute(ctx, { script: SCRIPT }) + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('requires a calling agent') + expect(engine.requests.length).toBe(0) + }) + + it('validates its own arguments via the schema DSL (missing script)', async () => { + const { ctx, parent } = await setup() + const result = await execute(ctx, {}, { agent: parent }) + expect(result.isError).toBe(true) + expect(result.error?.code).toBe('INVALID_ARGS') + }) + + it('cancels the run when exec.signal is ALREADY aborted at call time', async () => { + const { ctx, engine, parent } = await setup() + const controller = new AbortController() + controller.abort() + const result = await execute(ctx, { script: SCRIPT }, { agent: parent, signal: controller.signal }) + expect(result.isError).toBe(true) + expect(engine.cancels).toContain('parent step aborted') + expect(engine.disposed).toBe(1) + }) + + it('truncates an oversized rendered value with a notice (maxResultChars)', async () => { + const { ctx, engine, parent } = await setup({ maxResultChars: 40 }) + const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) + engine.settle({ value: { blob: 'x'.repeat(500) }, stopReason: 'completed', agentsStarted: 1 }) + const rendered = ((await pending).content[0] as { text: string }).text + expect(rendered).toContain('[truncated:') + expect(rendered.length).toBeLessThan(400) + }) + + it('registers under a configured toolName and unregisters on fiber dispose (HMR safety)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(StubEngine) + const fiber = await ctx.plugin(toolWorkflow, { toolName: 'orchestrate' }) + expect(ctx.tools.get('orchestrate')).toBeDefined() + expect(ctx.tools.get('workflow')).toBeUndefined() + await fiber.dispose() + expect(ctx.tools.get('orchestrate')).toBeUndefined() + }) + + it('presents a generic pending card titled by the sniffed meta name, with the script as rawInput', async () => { + const { ctx } = await setup() + const tool = ctx.tools.get('workflow')! + const view = tool.presentCall!({ script: SCRIPT }) + expect(view).toMatchObject({ card: 'generic', title: 'workflow: audit', rawInput: SCRIPT }) + const anonymous = tool.presentCall!({ script: 'export const meta = {}\nreturn 1' }) + expect(anonymous).toMatchObject({ card: 'generic', title: 'workflow' }) + }) + + it('presentResult keeps the generic card; presentation is pure and replay-safe on malformed args', async () => { + const { ctx } = await setup() + const tool = ctx.tools.get('workflow')! + expect(tool.presentResult!({ script: SCRIPT }, { content: [], isError: false })).toEqual({ card: 'generic' }) + // defineTool soft-validates presentation args: a malformed logged shape + // falls back to undefined instead of throwing mid-replay. + expect(tool.presentCall!({ not: 'the schema' })).toBeUndefined() + }) + + it('has the namespace-plugin export shape (no stray default)', () => { + expect('default' in toolWorkflow).toBe(false) + expect(toolWorkflow.name).toBe('tool-workflow') + expect(toolWorkflow.inject).toEqual(['tools', 'workflows']) + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(toolWorkflow) as Record + expect(unwrapped).toBe(toolWorkflow) + expect(typeof unwrapped.apply).toBe('function') + }) +}) diff --git a/packages/workflow/tool-workflow/tsconfig.json b/packages/workflow/tool-workflow/tsconfig.json new file mode 100644 index 0000000000..25f4d989f2 --- /dev/null +++ b/packages/workflow/tool-workflow/tsconfig.json @@ -0,0 +1,33 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../core/tools" + }, + { + "path": "../workflow" + } + ] +} diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md new file mode 100644 index 0000000000..1cbc76c250 --- /dev/null +++ b/packages/workflow/workflow-vm/README.md @@ -0,0 +1,30 @@ +# @deepseek-ai/dsh-workflow-vm + +The first [`WorkflowService`](../workflow/README.md) implementation: an in-process **`node:vm` engine**. It parses the Claude Code-format script (`export const meta = {...}` + plain-JS body), runs the body in a fresh vm context with the workflow hooks injected, and fans `agent()` calls out to [`ctx.subagents`](../../subagent/README.md). + +## The script contract it executes + +- **Meta extraction** (`extractMeta`): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. +- **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline). +- **Determinism bans**: `Date.now()`, `Math.random()`, and argless `new Date()` throw (kept even though resume is deferred, so scripts stay resume-compatible); no timers, filesystem, or Node APIs exist in the context. + +## Realm discipline + +Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a descriptor walk that never invokes accessors and rejects loud everything JSON cannot carry (accessors, exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values ENTERING the realm (`args`, `agent()` results) are rebuilt INSIDE the realm through the context's own `JSON.parse`, so the script never holds an object whose prototype chain reaches host intrinsics. + +## Limits, cancellation, disposal + +Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`. Once a run settles, stray children a script fired without awaiting are aborted too. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). + +**Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin after the first await cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). + +## Config + +| Key | Default | Meaning | +|---|---|---| +| `provider` | `spawn` | The `ctx.subagents` provider children run on. | +| `maxConcurrentAgents` | `0` (auto) | Concurrent `agent()` ceiling; `0` resolves to `min(16, max(1, cores - 2))`. | +| `maxTotalAgents` | `1000` | Total `agent()` calls one run may start (runaway-loop backstop). | +| `maxItemsPerCall` | `4096` | Items accepted by one `parallel()`/`pipeline()` call. | +| `syncTimeoutMs` | `5000` | vm timeout for the initial synchronous slice and the meta evaluation. | +| `disposeGraceMs` | `5000` | How long `dispose()` waits for a cancelled script before abandoning it. | diff --git a/packages/workflow/workflow-vm/package.json b/packages/workflow/workflow-vm/package.json new file mode 100644 index 0000000000..8b1217acc0 --- /dev/null +++ b/packages/workflow/workflow-vm/package.json @@ -0,0 +1,50 @@ +{ + "name": "@deepseek-ai/dsh-workflow-vm", + "description": "node:vm workflow engine: executes model-written orchestration scripts over ctx.subagents", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-subagent": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "@deepseek-ai/dsh-workflow": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-subagent": "workspace:^", + "@deepseek-ai/dsh-subagent-spawn": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "@deepseek-ai/dsh-workflow": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-vm/src/index.ts new file mode 100644 index 0000000000..914ebb3ba6 --- /dev/null +++ b/packages/workflow/workflow-vm/src/index.ts @@ -0,0 +1,166 @@ +/** + * The `node:vm` workflow engine: the first {@link WorkflowService} + * implementation. Parses the Claude Code-format script (meta + body), runs the + * body in a fresh in-process vm context with the workflow hooks injected, and + * fans `agent()` calls out to `ctx.subagents`. + * + * Engine limitations, documented as the accepted cost of the in-process + * mechanism (the interface/implementation seam exists precisely so a + * worker-thread or isolated-vm engine can swap in if these ever matter): + * + * - vm is NOT a security boundary. Scripts are model-written — the same trust + * level as the model's bash access — and the realm-boundary materialization + * is correctness containment, not a sandbox. + * - The vm `timeout` covers only the initial SYNCHRONOUS slice of the script; + * a pathological synchronous spin after the first await cannot be killed + * in-process. `dispose()` therefore waits a bounded grace and then ABANDONS + * a stuck script: its pending hook promises are already rejected and its + * settlement is contained (no unhandled rejection), but an abandoned + * synchronous spin would still occupy the event loop. + * + * Plugin export shape: a default-exported {@link WorkflowService} subclass + * (the class-based service form, like `dsh-bash-local`). + * + * @module @deepseek-ai/dsh-workflow-vm + */ + +import { randomUUID } from 'node:crypto' +import { availableParallelism } from 'node:os' +import type { Context } from 'cordis' +import z from 'schemastery' +import WorkflowService, { WorkflowRunId } from '@deepseek-ai/dsh-workflow' +import type { WorkflowResult, WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' +import { extractMeta } from './meta.ts' +import { WorkflowExecution, type ExecutionLimits } from './runtime.ts' + +export { extractMeta, type ExtractedScript } from './meta.ts' +export { materializeFromRealm, MaterializeError } from './realm.ts' +export { WorkflowExecution, type ExecutionLimits, type ExecutionObserver } from './runtime.ts' + +/** Plugin config (all optional — `static Config` supplies the defaults). */ +export interface Config { + /** The `ctx.subagents` provider children run on (default `spawn`). */ + provider?: string + /** Concurrent `agent()` ceiling; `0` (the default) auto-resolves to `min(16, max(1, cores - 2))`. */ + maxConcurrentAgents?: number + /** Total `agent()` calls one run may start — the runaway-loop backstop (default 1000). */ + maxTotalAgents?: number + /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */ + maxItemsPerCall?: number + /** vm timeout for the script's initial synchronous slice AND the meta-literal evaluation (default 5000 ms). */ + syncTimeoutMs?: number + /** How long `dispose()` waits for a cancelled script to settle before abandoning it (default 5000 ms). */ + disposeGraceMs?: number +} + +type ResolvedConfig = Required + +/** + * The vm engine service. `start()` validates the script up front (meta + + * body compile) and returns a {@link WorkflowRun} whose `result` never + * rejects; the `workflow/*` events fire around the run per the seam contract. + */ +export class VmWorkflowEngine extends WorkflowService { + static inject = ['subagents'] + + static Config: z = z.object({ + provider: z.string().default('spawn'), + maxConcurrentAgents: z.natural().default(0), + maxTotalAgents: z.natural().min(1).default(1000), + maxItemsPerCall: z.natural().min(1).default(4096), + syncTimeoutMs: z.natural().min(1).default(5000), + disposeGraceMs: z.natural().default(5000), + }) + + private readonly config: ResolvedConfig + + constructor(ctx: Context, config: Config) { + super(ctx) + // schemastery (static Config) has already filled the defaulted fields; + // the assertion records that resolution, not a hidden fallback. + this.config = config as ResolvedConfig + } + + /** + * Parse and execute a workflow script. Throws {@link WorkflowError} + * synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot + * begin; once a run is returned, every failure resolves through + * `result.stopReason` instead. + * @param request - the script, its `args`, the parent agent, and an + * optional cancel signal. + * @returns the live run (its `result` resolves when the script settles). + */ + start(request: WorkflowStartRequest): WorkflowRun { + const { meta, body } = extractMeta(request.script, this.config.syncTimeoutMs) + const id = WorkflowRunId(randomUUID()) + // The event payloads and the run handle get SEPARATE meta clones: a + // listener mutating its snapshot must not corrupt the holder's view. + const info: WorkflowRunInfo = { id, meta: structuredClone(meta) } + const limits: ExecutionLimits = { + provider: this.config.provider, + maxConcurrentAgents: this.config.maxConcurrentAgents === 0 + ? Math.min(16, Math.max(1, availableParallelism() - 2)) + : this.config.maxConcurrentAgents, + maxTotalAgents: this.config.maxTotalAgents, + maxItemsPerCall: this.config.maxItemsPerCall, + syncTimeoutMs: this.config.syncTimeoutMs, + } + const execution = new WorkflowExecution( + this.ctx, + meta, + body, + request.parent, + request.args, + request.signal, + limits, + { + phase: (title) => { this.emitWorkflowEvent('workflow/phase', info, title) }, + log: (message) => { this.emitWorkflowEvent('workflow/log', info, message) }, + agentStart: (agent) => { this.emitWorkflowEvent('workflow/agent-start', info, agent) }, + agentEnd: (agent) => { this.emitWorkflowEvent('workflow/agent-end', info, agent) }, + }, + ) + + this.emitWorkflowEvent('workflow/start', info) + const result: Promise = execution.drive() + // `workflow/end` fires as the (never-rejecting) result settles, with the + // outcome DATA only — the value stays with the run's holder. + void result.then((settled) => { + this.emitWorkflowEvent('workflow/end', info, { + stopReason: settled.stopReason, + ...settled.error !== undefined ? { error: settled.error } : {}, + agentsStarted: settled.agentsStarted, + }) + }) + + let disposed: Promise | undefined + return { + id, + meta: structuredClone(meta), + result, + cancel(reason?: string): void { + execution.cancel(reason) + }, + dispose: (): Promise => { + // Idempotent: cancel, then wait min(settle, grace). `result` never + // rejects, so the race needs no rejection handling; an unsettled + // script past the grace is abandoned per the module contract. + disposed ??= (async () => { + execution.cancel('workflow disposed') + await Promise.race([result, sleep(this.config.disposeGraceMs)]) + })() + return disposed + }, + } + } +} + +/** A plain timer sleep (the dispose grace); unref'd so it never holds the process open. */ +function sleep(ms: number): Promise { + return new Promise((resolve) => { + const timer = setTimeout(resolve, ms) + timer.unref() + }) +} + +export default VmWorkflowEngine diff --git a/packages/workflow/workflow-vm/src/meta.ts b/packages/workflow/workflow-vm/src/meta.ts new file mode 100644 index 0000000000..bb97ad7d39 --- /dev/null +++ b/packages/workflow/workflow-vm/src/meta.ts @@ -0,0 +1,198 @@ +/** + * Meta-block extraction: turn a Claude Code-format workflow script — + * `export const meta = {...}` followed by a plain-JS body — into a validated + * {@link WorkflowMeta} plus the body with the meta statement blanked + * line-preservingly (error stacks keep the script's own line numbers). + * + * The scanner is a small string/comment-aware brace matcher, not a JS parser: + * it only has to find the END of the meta object literal, and the literal is + * contractually PURE (no interpolation, no computed values). Template strings + * are tolerated as plain quotes but `${` inside one is rejected up front — + * interpolation is where "literal" stops being checkable by evaluation. The + * extracted text is then evaluated ALONE in an empty, timed vm context (a + * non-literal reference throws there; an expression can still RUN, so the + * result — not the source — is the contract: it must materialize to plain + * JSON data and pass the shape validation). + * + * @module @deepseek-ai/dsh-workflow-vm/meta + */ + +import * as vm from 'node:vm' +import { WorkflowError } from '@deepseek-ai/dsh-workflow' +import type { WorkflowMeta, WorkflowPhase } from '@deepseek-ai/dsh-workflow' +import { materializeFromRealm, MaterializeError } from './realm.ts' + +/** The result of {@link extractMeta}: the validated meta and the runnable body. */ +export interface ExtractedScript { + meta: WorkflowMeta + /** The script with the meta statement blanked (newlines preserved). */ + body: string +} + +const META_PREFIX = /^\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*|\s+)*export\s+const\s+meta\s*=\s*/ + +/** + * Scan `source` from `start` (an opening `{`) to its matching `}`, aware of + * string literals (`'`/`"`/backtick, with escapes) and comments. Returns the + * index AFTER the closing brace. Throws `SCRIPT_PARSE` on template + * interpolation (`${` inside a backtick string) or an unterminated literal. + */ +function scanObjectLiteral(source: string, start: number): number { + let depth = 0 + let index = start + while (index < source.length) { + const ch = source.charAt(index) + if (ch === '/' && source[index + 1] === '/') { + const end = source.indexOf('\n', index) + index = end === -1 ? source.length : end + 1 + continue + } + if (ch === '/' && source[index + 1] === '*') { + const end = source.indexOf('*/', index + 2) + if (end === -1) throw new WorkflowError('meta block has an unterminated comment', 'SCRIPT_PARSE') + index = end + 2 + continue + } + if (ch === '\'' || ch === '"' || ch === '`') { + index = scanString(source, index, ch) + continue + } + if (ch === '{' || ch === '[') depth += 1 + if (ch === '}' || ch === ']') { + depth -= 1 + if (depth === 0) return index + 1 + } + index += 1 + } + throw new WorkflowError('meta block is not a balanced object literal', 'SCRIPT_PARSE') +} + +/** Scan past one string literal starting at `start` (the quote char); returns the index after the closing quote. */ +function scanString(source: string, start: number, quote: string): number { + let index = start + 1 + while (index < source.length) { + const ch = source.charAt(index) + if (ch === '\\') { + index += 2 + continue + } + if (quote === '`' && ch === '$' && source[index + 1] === '{') { + throw new WorkflowError('template interpolation (`${...}`) is not allowed in the meta block — meta must be a pure literal', 'SCRIPT_PARSE') + } + if (ch === quote) return index + 1 + index += 1 + } + throw new WorkflowError('meta block has an unterminated string literal', 'SCRIPT_PARSE') +} + +/** Replace `[from, to)` of `source` with whitespace, preserving every newline (line numbers survive). */ +function blankSpan(source: string, from: number, to: number): string { + const blanked = source.slice(from, to).replace(/[^\n]/g, ' ') + return source.slice(0, from) + blanked + source.slice(to) +} + +/** Collect shape violations for an evaluated meta value (already materialized to host JSON data). */ +function validateMetaShape(meta: unknown): { meta?: WorkflowMeta; violations: string[] } { + const violations: string[] = [] + /* v8 ignore next 3 -- defensive: the scanner only extracts a brace-delimited literal, which always evaluates to a plain object */ + if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) { + return { violations: ['meta must be an object literal'] } + } + const record = meta as Record + const known = new Set(['name', 'description', 'whenToUse', 'phases']) + for (const key of Object.keys(record)) { + if (!known.has(key)) violations.push(`meta.${key} is not a recognized field (name/description/whenToUse/phases)`) + } + if (typeof record.name !== 'string' || record.name.length === 0) violations.push('meta.name must be a non-empty string') + if (typeof record.description !== 'string' || record.description.length === 0) violations.push('meta.description must be a non-empty string') + if (record.whenToUse !== undefined && typeof record.whenToUse !== 'string') violations.push('meta.whenToUse must be a string') + const phases: WorkflowPhase[] = [] + if (record.phases !== undefined) { + if (!Array.isArray(record.phases)) { + violations.push('meta.phases must be an array') + } else { + record.phases.forEach((phase, index) => { + if (typeof phase !== 'object' || phase === null || Array.isArray(phase)) { + violations.push(`meta.phases[${index}] must be an object`) + return + } + const entry = phase as Record + for (const key of Object.keys(entry)) { + if (!['title', 'detail', 'model'].includes(key)) violations.push(`meta.phases[${index}].${key} is not a recognized field`) + } + if (typeof entry.title !== 'string' || entry.title.length === 0) violations.push(`meta.phases[${index}].title must be a non-empty string`) + if (entry.detail !== undefined && typeof entry.detail !== 'string') violations.push(`meta.phases[${index}].detail must be a string`) + if (entry.model !== undefined && typeof entry.model !== 'string') violations.push(`meta.phases[${index}].model must be a string`) + if (violations.length === 0) { + phases.push({ + title: entry.title as string, + ...entry.detail !== undefined ? { detail: entry.detail as string } : {}, + ...entry.model !== undefined ? { model: entry.model as string } : {}, + }) + } + }) + } + } + if (violations.length > 0) return { violations } + return { + violations, + meta: { + name: record.name as string, + description: record.description as string, + ...record.whenToUse !== undefined ? { whenToUse: record.whenToUse as string } : {}, + ...record.phases !== undefined ? { phases } : {}, + }, + } +} + +/** + * Extract and validate the leading `export const meta = {...}` statement. + * Throws {@link WorkflowError} — `SCRIPT_PARSE` when the statement is missing + * or unscannable, `META_INVALID` when the literal evaluates to something + * outside the meta contract (non-JSON data, wrong shape, unknown fields). + * @param script - the full script text. + * @param evalTimeoutMs - the vm timeout for evaluating the extracted literal. + * @returns the validated meta and the line-preservingly blanked body. + */ +export function extractMeta(script: string, evalTimeoutMs: number): ExtractedScript { + const match = META_PREFIX.exec(script) + if (!match) { + throw new WorkflowError('script must begin with `export const meta = {...}` (leading comments allowed)', 'SCRIPT_PARSE') + } + const literalStart = match[0].length + if (script[literalStart] !== '{') { + throw new WorkflowError('`export const meta =` must be followed by an object literal', 'SCRIPT_PARSE') + } + const literalEnd = scanObjectLiteral(script, literalStart) + const literal = script.slice(literalStart, literalEnd) + + let evaluated: unknown + try { + // An EMPTY context: any non-literal reference (a variable, a call) throws + // here. The result — data only — is what the contract checks; a getter or + // IIFE can still run, which is why the timeout and the materialization + // below are part of the same boundary. + evaluated = vm.runInNewContext(`(${literal})`, undefined, { timeout: evalTimeoutMs }) + } catch (error: unknown) { + throw new WorkflowError(`meta block failed to evaluate as a pure literal: ${String(error)}`, 'META_INVALID', { cause: error }) + } + let data: unknown + try { + data = materializeFromRealm(evaluated, 'meta') + } catch (error: unknown) { + /* v8 ignore next -- defensive rethrow arm: materializeFromRealm only throws MaterializeError */ + if (!(error instanceof MaterializeError)) throw error + throw new WorkflowError(`meta block is not pure JSON data — ${error.message}`, 'META_INVALID', { cause: error }) + } + const { meta, violations } = validateMetaShape(data) + if (meta === undefined) { + throw new WorkflowError(`invalid meta block: ${violations.join('; ')}`, 'META_INVALID') + } + + // Blank the whole statement (including a trailing semicolon, if any) so the + // body compiles standalone with its original line numbers. + let statementEnd = literalEnd + while (statementEnd < script.length && (script[statementEnd] === ' ' || script[statementEnd] === '\t')) statementEnd += 1 + if (script[statementEnd] === ';') statementEnd += 1 + return { meta, body: blankSpan(script, 0, statementEnd) } +} diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts new file mode 100644 index 0000000000..70745cb4f6 --- /dev/null +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -0,0 +1,142 @@ +/** + * Realm-boundary materialization for the vm engine. + * + * Values produced INSIDE the script realm (the meta literal, hook arguments, + * the script's return value) must become plain host-realm JSON data before the + * host touches them. The repo's `isJsonValue` guard cannot run first: it is + * prototype-strict (any cross-realm object fails it) and it INVOKES getters + * (letting realm code run outside the vm's timed window). So this module walks + * own-property DESCRIPTORS — never invoking accessors — and copies data into + * host containers, rejecting loud everything JSON cannot carry: + * accessor properties, non-plain prototypes, functions, symbols (keys or + * values), bigints, non-finite numbers, `undefined` values, cycles, sparse + * arrays, and arrays with non-index own properties. + * + * Host objects are built with `Object.defineProperty` into a fresh `{}` — + * never plain `target[key] =` assignment, which a `"__proto__"` key would turn + * into prototype mutation instead of a data property. + * + * The host→realm direction deliberately does NOT live here: a host object + * handed into the realm would expose host intrinsics through its prototype + * chain, so the engine rebuilds inbound values INSIDE the realm via the + * context's own `JSON.parse` (see the runtime). + * + * @module @deepseek-ai/dsh-workflow-vm/realm + */ + +/** Thrown by {@link materializeFromRealm}; the caller wraps it into the right `WorkflowError` code. */ +export class MaterializeError extends Error { + constructor(public readonly path: string, public readonly reason: string) { + super(`${path}: ${reason}`) + this.name = 'MaterializeError' + } +} + +/** + * Whether an object's prototype chain is data-shaped: `null`, or a prototype + * whose own prototype is `null` (the realm's `Object.prototype` — which we + * cannot compare by identity across realms). A `Date`/`Map`/class instance + * has a longer chain and is rejected. + */ +function hasPlainPrototype(value: object): boolean { + const proto: unknown = Object.getPrototypeOf(value) + if (proto === null) return true + return Object.getPrototypeOf(proto) === null +} + +/** + * Copy `value` (typically from the vm realm) into plain host JSON data. + * Throws {@link MaterializeError} naming the offending path for anything JSON + * cannot carry losslessly. Accessors are detected via descriptors and NEVER + * invoked. `undefined` is accepted only at the ROOT (a script with no + * `return` value) — the caller decides what it means; an `undefined` nested + * INSIDE a container is a violation. + * @param value - the realm value to materialize. + * @param root - the path label for the root value (error messages). + * @returns the host-realm copy (plain objects/arrays/scalars only). + */ +export function materializeFromRealm(value: unknown, root = 'value'): unknown { + if (value === undefined) return undefined + return materialize(value, root, new Set()) +} + +function materialize(value: unknown, path: string, seen: Set): unknown { + switch (typeof value) { + case 'boolean': + case 'string': + return value + case 'number': { + if (!Number.isFinite(value)) throw new MaterializeError(path, 'non-finite numbers are not JSON data') + return value + } + case 'bigint': + throw new MaterializeError(path, 'bigints are not JSON data') + case 'function': + throw new MaterializeError(path, 'functions cannot cross the workflow realm boundary') + case 'symbol': + throw new MaterializeError(path, 'symbols cannot cross the workflow realm boundary') + case 'undefined': + throw new MaterializeError(path, 'undefined is not JSON data') + case 'object': + break + } + if (value === null) return null + const objectValue: object = value + if (seen.has(objectValue)) throw new MaterializeError(path, 'circular references are not JSON data') + seen.add(objectValue) + try { + if (Array.isArray(objectValue)) return materializeArray(objectValue, path, seen) + return materializeObject(objectValue, path, seen) + } finally { + seen.delete(objectValue) + } +} + +function materializeArray(value: unknown[], path: string, seen: Set): unknown[] { + const out: unknown[] = [] + for (let index = 0; index < value.length; index++) { + const descriptor = Object.getOwnPropertyDescriptor(value, index) + if (descriptor === undefined) throw new MaterializeError(`${path}[${index}]`, 'sparse arrays are not JSON data') + if (!('value' in descriptor)) throw new MaterializeError(`${path}[${index}]`, 'accessor properties cannot cross the workflow realm boundary') + out.push(materialize(descriptor.value, `${path}[${index}]`, seen)) + } + // Own enumerable props beyond the indices (e.g. `arr.total = 3`) would be + // silently dropped by JSON — reject them instead. + for (const key of Object.keys(value)) { + const index = Number(key) + if (!Number.isInteger(index) || index < 0 || index >= value.length) { + throw new MaterializeError(`${path}.${key}`, 'arrays with non-index properties are not JSON data') + } + } + if (Object.getOwnPropertySymbols(value).length > 0) { + throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow realm boundary') + } + return out +} + +function materializeObject(value: object, path: string, seen: Set): Record { + if (!hasPlainPrototype(value)) { + throw new MaterializeError(path, 'only plain objects and arrays are JSON data (exotic prototype)') + } + if (Object.getOwnPropertySymbols(value).length > 0) { + throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow realm boundary') + } + const out: Record = {} + for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) { + // Non-enumerable own props never reach JSON output — skip them, matching + // JSON.stringify's contract exactly (documented in the module doc). + if (!descriptor.enumerable) continue + if (!('value' in descriptor)) { + throw new MaterializeError(`${path}.${key}`, 'accessor properties cannot cross the workflow realm boundary') + } + // defineProperty, never assignment: a "__proto__" key must become an OWN + // data property of the copy, not a prototype mutation. + Object.defineProperty(out, key, { + value: materialize(descriptor.value, `${path}.${key}`, seen), + enumerable: true, + writable: true, + configurable: true, + }) + } + return out +} diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts new file mode 100644 index 0000000000..04176a11ac --- /dev/null +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -0,0 +1,499 @@ +/** + * Per-run execution state for the vm workflow engine: the script context and + * its injected hooks (`agent`/`parallel`/`pipeline`/`phase`/`log`/`args`), the + * concurrency semaphore and caps, cancellation, and the drive loop that turns + * a script settlement into a {@link WorkflowResult}. + * + * Realm discipline (see also ./realm.ts): values ENTERING the host from the + * script (hook options, schemas, the return value) are materialized via + * descriptor walks; values ENTERING the realm from the host (`args`, agent() + * results) are rebuilt INSIDE the realm through the context's own + * `JSON.parse`, so the script never holds an object whose prototype chain + * reaches host intrinsics. Realm functions (pipeline stages, parallel thunks) + * are called, not materialized — their values stay realm-side. + * + * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments, + * unsupported options/schemas, tripped caps, seam start failures, + * cancellation) ALWAYS propagate through `parallel`/`pipeline`; the per-item + * `null` is reserved for child-run failures and ordinary in-stage script + * errors. Every hook-returned promise gets a no-op rejection consumer + * attached, so a script that drops a promise (fires an `agent()` without + * awaiting it) cannot surface an unhandled rejection when cancellation + * rejects it — the app boot layer exits the process on unhandled rejections. + * + * @module @deepseek-ai/dsh-workflow-vm/runtime + */ + +import * as vm from 'node:vm' +import type { Context } from 'cordis' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type {} from '@deepseek-ai/dsh-subagent' +import { assertSupportedOutputSchema, OutputSchemaError } from '@deepseek-ai/dsh-tools' +import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' +import { WorkflowError, isFatalWorkflowError } from '@deepseek-ai/dsh-workflow' +import type { + WorkflowAgentEndInfo, + WorkflowAgentInfo, + WorkflowMeta, + WorkflowResult, +} from '@deepseek-ai/dsh-workflow' +import { materializeFromRealm, MaterializeError } from './realm.ts' + +/** The per-run knobs the engine resolves from its Config. */ +export interface ExecutionLimits { + /** The `ctx.subagents` provider name to start children on. */ + provider: string + /** Concurrent `agent()` ceiling (already auto-resolved; ≥ 1). */ + maxConcurrentAgents: number + /** Total `agent()` calls per run (the runaway-loop backstop). */ + maxTotalAgents: number + /** Items accepted by one `parallel()`/`pipeline()` call. */ + maxItemsPerCall: number + /** vm timeout for the script's initial synchronous slice. */ + syncTimeoutMs: number +} + +/** The engine-side observers the execution reports progress through. */ +export interface ExecutionObserver { + phase(title: string): void + log(message: string): void + agentStart(info: WorkflowAgentInfo): void + agentEnd(info: WorkflowAgentEndInfo): void +} + +/** The `agent()` options the script may pass; everything else rejects loud. */ +const SUPPORTED_AGENT_OPTIONS = new Set(['label', 'phase', 'schema', 'model']) +/** Deferred Claude Code options we name explicitly in the rejection message. */ +const DEFERRED_AGENT_OPTIONS = new Set(['effort', 'isolation', 'agentType']) + +/** The in-context prelude that bans the nondeterminism sources (kept even though resume is deferred, so scripts stay resume-compatible). */ +const DETERMINISM_PRELUDE = ` +{ + const banned = (name) => () => { + throw new Error(name + ' is not available in workflow scripts (runs must stay deterministic for future resume support; pass timestamps in via args)') + } + Math.random = banned('Math.random()') + Date.now = banned('Date.now()') + const RealDate = Date + globalThis.Date = new Proxy(RealDate, { + construct(target, args, newTarget) { + if (args.length === 0) banned('argless new Date()')() + return Reflect.construct(target, args, newTarget) + }, + apply: banned('Date()'), + }) +} +` + +/** Flatten a child's final output blocks to text (the non-schema `agent()` result). */ +function outputText(blocks: ContentBlock[]): string { + return blocks + .filter((block): block is Extract => block.type === 'text') + .map(block => block.text) + .join('') +} + +/** + * Render a script failure for the result: prefer the stack (it carries the + * script's own line numbers via the compile lineOffset), then the message. + * STRUCTURAL detection, not `instanceof Error` — a realm-thrown Error is not + * an instance of the host Error class. + */ +function errorText(error: unknown): string { + if (typeof error === 'object' && error !== null) { + const maybe = error as { stack?: unknown; message?: unknown } + if (typeof maybe.stack === 'string' && maybe.stack.length > 0) return maybe.stack + if (typeof maybe.message === 'string') return maybe.message + } + return String(error) +} + +/** A short display label derived from the prompt when the script passes none. */ +function defaultLabel(prompt: string): string { + const newline = prompt.indexOf('\n') + const line = newline === -1 ? prompt : prompt.slice(0, newline) + return line.length <= 48 ? line : `${line.slice(0, 47)}…` +} + +/** + * One live script execution. Constructed per run by the engine; `drive()` is + * called exactly once and NEVER rejects — every failure becomes a + * {@link WorkflowResult} with a non-`completed` stop reason. + */ +export class WorkflowExecution { + /** 1-based count of `agent()` calls started (the `agentsStarted` result field). */ + private started = 0 + private activeSlots = 0 + private readonly slotWaiters: { resolve(): void; reject(error: unknown): void }[] = [] + private cancelReason: string | undefined + private cancelError: WorkflowError | undefined + private readonly controller = new AbortController() + private currentPhase: string | undefined + private readonly context: vm.Context + private readonly realmJsonParse: (text: string) => unknown + private readonly compiled: vm.Script + + constructor( + private readonly ctx: Context, + meta: WorkflowMeta, + body: string, + private readonly parent: Agent, + args: unknown, + signal: AbortSignal | undefined, + private readonly limits: ExecutionLimits, + private readonly observer: ExecutionObserver, + ) { + // Compile FIRST: a body syntax error must throw out of the constructor + // (the engine maps it to SCRIPT_PARSE) before any realm state exists. + // lineOffset compensates for the wrapper line, so stack traces carry the + // script's own line numbers (the meta statement was blanked, not removed). + try { + this.compiled = new vm.Script(`(async () => {\n${body}\n})()`, { + filename: `workflow:${meta.name}`, + lineOffset: -1, + }) + } catch (error: unknown) { + throw new WorkflowError(`workflow script does not parse: ${String(error)}`, 'SCRIPT_PARSE', { cause: error }) + } + + this.context = vm.createContext({}, { name: `workflow:${meta.name}` }) + vm.runInContext(DETERMINISM_PRELUDE, this.context) + // The realm's own JSON.parse — the host→realm rebuild channel. + const realmJson = vm.runInContext('JSON', this.context) as { parse(text: string): unknown } + this.realmJsonParse = (text: string) => realmJson.parse(text) + + const globals: Record = { + agent: (prompt: unknown, opts?: unknown) => this.contain(this.agent(prompt, opts)), + parallel: (thunks: unknown) => this.contain(this.parallel(thunks)), + pipeline: (items: unknown, ...stages: unknown[]) => this.contain(this.pipeline(items, stages)), + phase: (title: unknown) => { this.phase(title) }, + log: (message: unknown) => { this.log(message) }, + args: this.toRealm(args), + } + for (const [key, value] of Object.entries(globals)) { + // Data properties on the contextified global; frozen shape not required — + // a script overwriting its own hooks only sabotages itself. + ;(this.context as Record)[key] = typeof value === 'function' ? Object.freeze(value) : value + } + + if (signal?.aborted) { + this.cancel('workflow start signal already aborted') + } else { + signal?.addEventListener('abort', () => { this.cancel('workflow signal aborted') }, { once: true }) + } + } + + /** + * Whether the run has been cancelled. A METHOD, not an inline property + * read: `cancel()` mutates `cancelReason` concurrently (a signal listener, + * a raced dispose), and an inline read after an `await` gets narrowed by + * control flow into an always-false comparison. + */ + private isCancelled(): boolean { + return this.cancelReason !== undefined + } + + /** + * Cancel the run: children abort (the shared signal), waiting `agent()` + * slots reject, and every future hook call throws `CANCELLED` — the script + * dies at its next await. Idempotent; the first reason wins. + */ + cancel(reason?: string): void { + if (this.cancelReason !== undefined) return + this.cancelReason = reason ?? 'workflow cancelled' + this.cancelError = new WorkflowError(`workflow run cancelled: ${this.cancelReason}`, 'CANCELLED') + this.controller.abort(this.cancelReason) + for (const waiter of this.slotWaiters.splice(0)) waiter.reject(this.cancelledError()) + } + + /** + * Run the script to settlement. Resolves — never rejects — with the run's + * {@link WorkflowResult}: the materialized return value on `completed`, the + * failure message on `error`, and `cancelled` when the script died of + * cancellation. After settlement, any stray children a script fired without + * awaiting are aborted (their `agent()` wrappers dispose them). + */ + async drive(): Promise { + try { + const scriptPromise = this.compiled.runInContext(this.context, { timeout: this.limits.syncTimeoutMs }) as Promise + const raw: unknown = await this.contain(Promise.resolve(scriptPromise)) + const value = raw === undefined ? null : this.materializeResult(raw) + return { value, stopReason: 'completed', agentsStarted: this.started } + } catch (error: unknown) { + if (error instanceof WorkflowError && error.code === 'CANCELLED') { + return { value: null, stopReason: 'cancelled', error: error.message, agentsStarted: this.started } + } + return { value: null, stopReason: 'error', error: errorText(error), agentsStarted: this.started } + } finally { + // Reap strays: a script that fired agent() calls without awaiting them + // leaves live children behind after settlement — abort them all. (The + // per-call wrappers dispose each child; the contain() consumer keeps + // their rejections from going unhandled.) + if (this.cancelReason === undefined) this.cancel('workflow settled') + } + } + + /** + * Attach a no-op rejection consumer WITHOUT changing what the caller + * receives: if the script drops the promise (no await), cancellation cannot + * become an unhandled rejection (the app boot layer exits the process on + * those); if the script does await it, it still observes the rejection. + */ + private contain(promise: Promise): Promise { + promise.catch(() => { /* consumed: see method contract — a dropped hook promise must not surface an unhandled rejection */ }) + return promise + } + + private cancelledError(): WorkflowError { + // cancel() arms cancelError before any caller can observe isCancelled() + // === true; the fallback guards the type, not a reachable path. + /* v8 ignore next */ + return this.cancelError ?? new WorkflowError('workflow run cancelled', 'CANCELLED') + } + + /** Rebuild a host value inside the script realm (via the realm's own JSON.parse). */ + private toRealm(value: unknown): unknown { + if (value === undefined) return undefined + if (value === null) return null + if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value + return this.realmJsonParse(JSON.stringify(value)) + } + + /** Materialize the script's return value; violations become RESULT_UNSERIALIZABLE. */ + private materializeResult(raw: unknown): unknown { + try { + return materializeFromRealm(raw, 'workflow result') + } catch (error: unknown) { + /* v8 ignore next -- defensive rethrow arm: materializeFromRealm only throws MaterializeError */ + if (!(error instanceof MaterializeError)) throw error + throw new WorkflowError( + `the workflow's return value is not plain JSON data — ${error.message}. Return only JSON-serializable objects/arrays/scalars.`, + 'RESULT_UNSERIALIZABLE', + { cause: error }, + ) + } + } + + /** + * Acquire one concurrency slot (FIFO). Cancellation rejects QUEUED waiters + * (see {@link cancel}); the callers guard their own entry and post-acquire + * windows, so no cancelled-precheck is duplicated here. + */ + private acquireSlot(): Promise { + if (this.activeSlots < this.limits.maxConcurrentAgents) { + this.activeSlots += 1 + return Promise.resolve() + } + return new Promise((resolve, reject) => { + this.slotWaiters.push({ + resolve: () => { + this.activeSlots += 1 + resolve() + }, + reject, + }) + }) + } + + private releaseSlot(): void { + this.activeSlots -= 1 + const next = this.slotWaiters.shift() + if (next) next.resolve() + } + + /** The `agent(prompt, opts)` hook. */ + private async agent(rawPrompt: unknown, rawOpts: unknown): Promise { + if (this.isCancelled()) throw this.cancelledError() + if (typeof rawPrompt !== 'string' || rawPrompt.length === 0) { + throw new WorkflowError('agent() requires a non-empty prompt string', 'INVALID_ARGUMENT') + } + const opts = this.readAgentOptions(rawOpts) + if (this.started >= this.limits.maxTotalAgents) { + throw new WorkflowError( + `this run reached its total agent cap (${this.limits.maxTotalAgents}) — a runaway-loop backstop; raise maxTotalAgents in the engine config if the scale is intentional`, + 'AGENT_CAP', + ) + } + this.started += 1 + const seq = this.started + const label = opts.label ?? defaultLabel(rawPrompt) + const phase = opts.phase ?? this.currentPhase + + await this.acquireSlot() + try { + // No cancelled re-check here: a cancel cannot interleave between a + // waiter's resolution and this continuation (single-threaded, no await + // between them), and a child started moments after a cancel still dies + // via the shared abort signal — the CANCELLED mapping below covers it. + let run + try { + run = this.ctx.subagents.start(this.limits.provider, { + prompt: [{ type: 'text', text: rawPrompt }], + parent: this.parent, + signal: this.controller.signal, + ...opts.schema !== undefined ? { outputSchema: opts.schema } : {}, + ...opts.model !== undefined ? { agentOptions: { model: opts.model } } : {}, + }) + } catch (error: unknown) { + throw new WorkflowError(`agent() could not start a child on provider "${this.limits.provider}": ${String(error)}`, 'AGENT_START', { cause: error }) + } + const info: WorkflowAgentInfo = { seq, label, ...phase !== undefined ? { phase } : {}, childId: run.id } + this.observer.agentStart(info) + try { + const result = await run.result + if (result.stopReason === 'completed') { + if (opts.schema !== undefined) { + // The provider honored outputSchema (capability-gated at start), so + // a completed run without a structured value is a child failure. + if (result.structured === undefined) { + this.observer.agentEnd({ ...info, outcome: 'failed' }) + return null + } + this.observer.agentEnd({ ...info, outcome: 'completed' }) + return this.toRealm(result.structured) + } + this.observer.agentEnd({ ...info, outcome: 'completed' }) + return outputText(result.output) + } + // A cancelled RUN kills the script; a child that failed for its own + // reasons resolves null (scripts .filter(Boolean) per the CC contract). + if (this.isCancelled()) { + this.observer.agentEnd({ ...info, outcome: 'cancelled' }) + throw this.cancelledError() + } + this.observer.agentEnd({ ...info, outcome: 'failed' }) + return null + } finally { + await run.dispose() + } + } finally { + this.releaseSlot() + } + } + + /** Materialize + validate the `agent()` options bag from the realm. */ + private readAgentOptions(rawOpts: unknown): { label?: string; phase?: string; model?: string; schema?: StructuredOutputSchema } { + if (rawOpts === undefined) return {} + let opts: unknown + try { + opts = materializeFromRealm(rawOpts, 'agent() options') + } catch (error: unknown) { + /* v8 ignore next -- defensive rethrow arm: materializeFromRealm only throws MaterializeError */ + if (!(error instanceof MaterializeError)) throw error + throw new WorkflowError(`agent() options must be plain JSON data — ${error.message}`, 'INVALID_ARGUMENT', { cause: error }) + } + if (typeof opts !== 'object' || opts === null || Array.isArray(opts)) { + throw new WorkflowError('agent() options must be an object', 'INVALID_ARGUMENT') + } + const record = opts as Record + for (const key of Object.keys(record)) { + if (SUPPORTED_AGENT_OPTIONS.has(key)) continue + if (DEFERRED_AGENT_OPTIONS.has(key)) { + throw new WorkflowError(`agent() option "${key}" is deferred and not supported by this engine (supported: label, phase, schema, model)`, 'UNSUPPORTED_OPTION') + } + throw new WorkflowError(`agent() option "${key}" is not recognized (supported: label, phase, schema, model)`, 'UNSUPPORTED_OPTION') + } + for (const key of ['label', 'phase', 'model'] as const) { + if (record[key] !== undefined && typeof record[key] !== 'string') { + throw new WorkflowError(`agent() option "${key}" must be a string`, 'INVALID_ARGUMENT') + } + } + let schema: StructuredOutputSchema | undefined + if (record.schema !== undefined) { + try { + assertSupportedOutputSchema(record.schema) + schema = record.schema + } catch (error: unknown) { + /* v8 ignore next -- defensive rethrow arm: assertSupportedOutputSchema only throws OutputSchemaError */ + if (!(error instanceof OutputSchemaError)) throw error + throw new WorkflowError(`agent() schema is outside the supported subset — ${error.message}`, 'UNSUPPORTED_SCHEMA', { cause: error }) + } + } + return { + ...record.label !== undefined ? { label: record.label as string } : {}, + ...record.phase !== undefined ? { phase: record.phase as string } : {}, + ...record.model !== undefined ? { model: record.model as string } : {}, + ...schema !== undefined ? { schema } : {}, + } + } + + /** The `parallel(thunks)` hook: each thunk caught → `null`; fatal errors propagate. */ + private async parallel(rawThunks: unknown): Promise { + if (!Array.isArray(rawThunks)) { + throw new WorkflowError('parallel() requires an array of zero-argument functions', 'INVALID_ARGUMENT') + } + this.assertItemCap(rawThunks.length, 'parallel()') + const thunks = rawThunks.map((thunk, index) => { + if (typeof thunk !== 'function') { + throw new WorkflowError(`parallel() item ${index} is not a function`, 'INVALID_ARGUMENT') + } + return thunk as () => unknown + }) + return Promise.all(thunks.map(async (thunk) => { + try { + return await thunk() + } catch (error: unknown) { + if (isFatalWorkflowError(error)) throw error + return null + } + })) + } + + /** The `pipeline(items, ...stages)` hook: per-item stage chains, NO cross-stage barrier. */ + private async pipeline(rawItems: unknown, rawStages: unknown[]): Promise { + if (!Array.isArray(rawItems)) { + throw new WorkflowError('pipeline() requires an items array', 'INVALID_ARGUMENT') + } + this.assertItemCap(rawItems.length, 'pipeline()') + if (rawStages.length === 0) { + throw new WorkflowError('pipeline() requires at least one stage function', 'INVALID_ARGUMENT') + } + const stages = rawStages.map((stage, index) => { + if (typeof stage !== 'function') { + throw new WorkflowError(`pipeline() stage ${index} is not a function`, 'INVALID_ARGUMENT') + } + return stage as (previous: unknown, item: unknown, index: number) => unknown + }) + return Promise.all(rawItems.map(async (item: unknown, index) => { + let value: unknown = item + try { + for (const stage of stages) { + value = await stage(value, item, index) + } + return value + } catch (error: unknown) { + // An ordinary stage throw drops the ITEM to null and skips its + // remaining stages; a fatal error kills the whole script. + if (isFatalWorkflowError(error)) throw error + return null + } + })) + } + + private assertItemCap(length: number, hook: string): void { + if (length > this.limits.maxItemsPerCall) { + throw new WorkflowError( + `${hook} received ${length} items — over the per-call cap (${this.limits.maxItemsPerCall}); split the work or raise maxItemsPerCall in the engine config`, + 'ITEM_CAP', + ) + } + } + + /** The `phase(title)` hook: sets the current label for subsequent `agent()` calls and notifies observers. */ + private phase(title: unknown): void { + if (typeof title !== 'string' || title.length === 0) { + throw new WorkflowError('phase() requires a non-empty title string', 'INVALID_ARGUMENT') + } + this.currentPhase = title + this.observer.phase(title) + } + + /** The `log(message)` hook: narration to observers. */ + private log(message: unknown): void { + if (typeof message !== 'string') { + throw new WorkflowError('log() requires a message string', 'INVALID_ARGUMENT') + } + this.observer.log(message) + } +} diff --git a/packages/workflow/workflow-vm/tests/integration.spec.ts b/packages/workflow/workflow-vm/tests/integration.spec.ts new file mode 100644 index 0000000000..48b308a986 --- /dev/null +++ b/packages/workflow/workflow-vm/tests/integration.spec.ts @@ -0,0 +1,89 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import * as Invariants from '@deepseek-ai/dsh-invariants' +import SubagentService from '@deepseek-ai/dsh-subagent' +import * as spawn from '@deepseek-ai/dsh-subagent-spawn' +import { STRUCTURED_OUTPUT_TOOL } from '@deepseek-ai/dsh-subagent-inprocess' +import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +import VmWorkflowEngine from '../src/index.ts' + +type Script = ConstructorParameters[0] + +/** + * The whole in-process stack, keyless: the vm engine drives the REAL spawn + * backend (with its structured runtime) on a real agent loop; the scripted + * mock MODEL is the only mocked boundary. This is the integration guard the + * per-hook unit tests (which stub the subagent seam) structurally cannot give. + */ +async function setup(script: Script) { + const ctx = new Context() + const adapter = new MockAdapter(script) + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(Invariants) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(SubagentService) + await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) + await ctx.plugin(VmWorkflowEngine, {}) + ctx.llm.registerAdapter(['mock'], adapter) + const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) + return { ctx, parent, adapter } +} + +describe('dsh-workflow-vm over the real in-process stack', () => { + it('runs a two-stage workflow: a plain child, then a schema child through the structured runtime', async () => { + const { ctx, parent } = await setup([ + textResponse('the file list is a.ts'), + toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { verdict: 'real', confidence: 0.9 }), + ]) + const childIds: string[] = [] + ctx.on('workflow/agent-start', (_info, agent) => { childIds.push(agent.childId) }) + const run = ctx.workflows.start({ + script: `export const meta = { name: 'integration', description: 'plain + structured children' } +phase('Read') +const prose = await agent('read the repo') +phase('Judge') +const judged = await agent('judge: ' + prose, { + schema: { type: 'object', properties: { verdict: { type: 'string', enum: ['real', 'bogus'] }, confidence: { type: 'number' } }, required: ['verdict'] }, +}) +return { prose, verdict: judged.verdict, confidence: judged.confidence }`, + parent, + }) + const result = await run.result + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ prose: 'the file list is a.ts', verdict: 'real', confidence: 0.9 }) + expect(result.agentsStarted).toBe(2) + await run.dispose() + // Both children were disposed to quiescence — no live child agents remain. + expect(childIds.length).toBe(2) + for (const childId of childIds) { + expect(ctx.agents.get(AgentId(childId))).toBeUndefined() + } + }) + + it('a child that fails against its schema (nudges exhausted) reaches the script as null', async () => { + const { ctx, parent } = await setup([ + textResponse('prose only'), + textResponse('still prose after the nudge'), + ]) + const run = ctx.workflows.start({ + script: `export const meta = { name: 'null-path', description: 'schema failure maps to null' } +const judged = await agent('judge it', { schema: { type: 'object', properties: { v: { type: 'string' } } } }) +return { got: judged === null ? 'null' : 'value' }`, + parent, + }) + const result = await run.result + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ got: 'null' }) + await run.dispose() + }) +}) diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-vm/tests/meta.spec.ts new file mode 100644 index 0000000000..4768da49ff --- /dev/null +++ b/packages/workflow/workflow-vm/tests/meta.spec.ts @@ -0,0 +1,143 @@ +import { describe, expect, it } from 'vitest' +import { WorkflowError } from '@deepseek-ai/dsh-workflow' +import { extractMeta } from '../src/meta.ts' + +const TIMEOUT = 1000 + +/** Extract and expect success. */ +function ok(script: string) { + return extractMeta(script, TIMEOUT) +} + +/** The WorkflowError a bad script produces (throws if it extracts cleanly). */ +function bad(script: string): WorkflowError { + try { + extractMeta(script, TIMEOUT) + } catch (error: unknown) { + if (error instanceof WorkflowError) return error + throw error + } + throw new Error('expected extraction to fail') +} + +describe('extractMeta', () => { + it('extracts a full meta block and blanks the statement line-preservingly', () => { + const script = `export const meta = { + name: 'audit-routes', + description: 'Audit every route', + whenToUse: 'when auditing', + phases: [{ title: 'Scan', detail: 'find files' }, { title: 'Fix', model: 'deepseek-v4-pro' }], +} +const x = 1 +return x` + const { meta, body } = ok(script) + expect(meta).toEqual({ + name: 'audit-routes', + description: 'Audit every route', + whenToUse: 'when auditing', + phases: [{ title: 'Scan', detail: 'find files' }, { title: 'Fix', model: 'deepseek-v4-pro' }], + }) + // Same line count; the statement's characters blanked; the body intact. + expect(body.split('\n').length).toBe(script.split('\n').length) + expect(body.split('\n')[6]).toBe('const x = 1') + expect(body).not.toContain('export') + }) + + it('allows leading line and block comments before the meta statement', () => { + const script = `// a workflow +/* multi + line */ +export const meta = { name: 'x', description: 'y' } +return 1` + expect(ok(script).meta.name).toBe('x') + }) + + it('handles braces inside strings and comments while scanning', () => { + const script = `export const meta = { + name: 'tricky', // } not a close { + /* } also not } */ + description: "has { braces } and 'quotes'", +} +return 2` + expect(ok(script).meta.description).toBe("has { braces } and 'quotes'") + }) + + it('tolerates template-quoted strings WITHOUT interpolation, escapes included', () => { + const script = 'export const meta = { name: `plain`, description: `esc \\` tick` }\nreturn 1' + expect(ok(script).meta.name).toBe('plain') + }) + + it('consumes a trailing semicolon after the literal, spaces included', () => { + const { body } = ok("export const meta = { name: 'x', description: 'y' };\nreturn 1") + expect(body).not.toContain(';') + expect(body.split('\n')[1]).toBe('return 1') + const spaced = ok("export const meta = { name: 'x', description: 'y' } ;\nreturn 1") + expect(spaced.body).not.toContain(';') + }) + + it('rejects a script that does not begin with the meta statement (SCRIPT_PARSE)', () => { + expect(bad('const a = 1').code).toBe('SCRIPT_PARSE') + expect(bad('').code).toBe('SCRIPT_PARSE') + expect(bad('export const meta = [1]').code).toBe('SCRIPT_PARSE') + }) + + it('rejects template interpolation in the meta block as impure (SCRIPT_PARSE)', () => { + const error = bad('export const meta = { name: `w-${1}`, description: "d" }\nreturn 1') + expect(error.code).toBe('SCRIPT_PARSE') + expect(error.message).toContain('pure literal') + }) + + it('rejects unbalanced literals, unterminated strings, and unterminated comments (SCRIPT_PARSE)', () => { + expect(bad('export const meta = { name: "x", description: "y"').code).toBe('SCRIPT_PARSE') + expect(bad('export const meta = { name: "x').code).toBe('SCRIPT_PARSE') + expect(bad('export const meta = { /* open').code).toBe('SCRIPT_PARSE') + // A line comment running to EOF (no newline) leaves the literal unbalanced. + expect(bad('export const meta = { name: "x" // eof comment').code).toBe('SCRIPT_PARSE') + }) + + it('rejects a literal referencing variables or calls (META_INVALID via the empty realm)', () => { + const error = bad('export const meta = { name: someVariable, description: "d" }\nreturn 1') + expect(error.code).toBe('META_INVALID') + expect(error.message).toContain('pure literal') + expect(bad('export const meta = { name: compute(), description: "d" }').code).toBe('META_INVALID') + }) + + it('rejects a literal evaluating to non-JSON data (META_INVALID via materialization)', () => { + const error = bad('export const meta = { name: "x", description: "d", phases: [{ get title() { return "t" } }] }') + expect(error.code).toBe('META_INVALID') + expect(error.message).toContain('JSON data') + }) + + it('rejects shape violations with EVERY violation listed (META_INVALID)', () => { + const error = bad('export const meta = { description: 7, bogus: 1 }\nreturn 1') + expect(error.code).toBe('META_INVALID') + expect(error.message).toContain('meta.name must be a non-empty string') + expect(error.message).toContain('meta.description must be a non-empty string') + expect(error.message).toContain('meta.bogus is not a recognized field') + }) + + it('rejects malformed whenToUse and phases shapes precisely', () => { + expect(bad('export const meta = { name: "x", description: "d", whenToUse: 3 }').message) + .toContain('meta.whenToUse must be a string') + expect(bad('export const meta = { name: "x", description: "d", phases: "no" }').message) + .toContain('meta.phases must be an array') + expect(bad('export const meta = { name: "x", description: "d", phases: [3] }').message) + .toContain('meta.phases[0] must be an object') + expect(bad('export const meta = { name: "x", description: "d", phases: [{}] }').message) + .toContain('meta.phases[0].title must be a non-empty string') + expect(bad('export const meta = { name: "x", description: "d", phases: [{ title: "t", extra: 1 }] }').message) + .toContain('meta.phases[0].extra is not a recognized field') + expect(bad('export const meta = { name: "x", description: "d", phases: [{ title: "t", detail: 1 }] }').message) + .toContain('meta.phases[0].detail must be a string') + expect(bad('export const meta = { name: "x", description: "d", phases: [{ title: "t", model: 1 }] }').message) + .toContain('meta.phases[0].model must be a string') + }) + + it('stops scanning at the balanced literal — trailing expression text stays in the body', () => { + // The scanner extracts exactly `{ valueOf: null }`; the ` && 3` is body + // text (which would fail compilation later, but extraction sees only the + // literal and reports its unknown field). + expect(bad('export const meta = { valueOf: null } && 3').message) + .toContain('meta.valueOf is not a recognized field') + }) +}) diff --git a/packages/workflow/workflow-vm/tests/realm.spec.ts b/packages/workflow/workflow-vm/tests/realm.spec.ts new file mode 100644 index 0000000000..f374706dba --- /dev/null +++ b/packages/workflow/workflow-vm/tests/realm.spec.ts @@ -0,0 +1,114 @@ +import { describe, expect, it } from 'vitest' +import * as vm from 'node:vm' +import { materializeFromRealm, MaterializeError } from '../src/realm.ts' + +/** Evaluate an expression inside a fresh vm realm and hand back the raw realm value. */ +function inRealm(expression: string): unknown { + return vm.runInNewContext(`(${expression})`) +} + +/** The MaterializeError message for a value that must be rejected (throws if accepted). */ +function rejection(value: unknown): string { + try { + materializeFromRealm(value) + } catch (error: unknown) { + if (error instanceof MaterializeError) return error.message + throw error + } + throw new Error('expected the value to be rejected') +} + +describe('materializeFromRealm', () => { + it('copies realm objects/arrays/scalars into host plain data', () => { + const value = inRealm("{ a: 1, b: 'x', c: true, d: null, list: [1, [2, { deep: 'y' }]] }") + const out = materializeFromRealm(value) as Record + expect(out).toEqual({ a: 1, b: 'x', c: true, d: null, list: [1, [2, { deep: 'y' }]] }) + // The copy is HOST data: prototypes are the host intrinsics. + expect(Object.getPrototypeOf(out)).toBe(Object.prototype) + expect(Array.isArray(out.list)).toBe(true) + // And it round-trips through JSON byte-identically (the whole point). + expect(JSON.parse(JSON.stringify(out))).toEqual(out) + }) + + it('accepts undefined ONLY at the root (a valueless script return)', () => { + expect(materializeFromRealm(undefined)).toBeUndefined() + expect(rejection(inRealm('{ a: undefined }'))).toContain('value.a') + }) + + it('never invokes accessors: a counting getter is rejected, not read', () => { + const counter = inRealm(` + (() => { + globalThis.reads = 0 + return { get x() { globalThis.reads += 1; return 1 } } + })() + `) + expect(rejection(counter)).toContain('accessor properties cannot cross') + // The getter body never ran — descriptor inspection only. + expect((counter as { x?: unknown }).x).toBe(1) // sanity: reading DOES run it… + expect(rejection(counter)).toContain('accessor') // …but materialization still never did + }) + + it('a "__proto__" key becomes an OWN data property of the copy, never a prototype mutation', () => { + const value: unknown = vm.runInNewContext('JSON.parse(\'{"__proto__": {"polluted": 1}, "ok": 2}\')') + const out = materializeFromRealm(value) as Record + expect(Object.getPrototypeOf(out)).toBe(Object.prototype) + expect(Object.prototype.hasOwnProperty.call(out, '__proto__')).toBe(true) + expect(out.ok).toBe(2) + // The host Object.prototype was NOT touched. + expect(({} as Record).polluted).toBeUndefined() + }) + + it('rejects functions, symbols (keys and values), and bigints with path-qualified messages', () => { + expect(rejection(inRealm('{ fn: () => 1 }'))).toContain('value.fn') + expect(rejection(inRealm("{ [Symbol('k')]: 1 }"))).toContain('symbol-keyed') + expect(rejection(inRealm("{ s: Symbol('v') }"))).toContain('value.s') + expect(rejection(inRealm('{ big: 1n }'))).toContain('value.big') + expect(rejection(inRealm("[Symbol('x')]"))).toContain('value[0]') + const taggedArray = inRealm("(() => { const a = [1]; a[Symbol('t')] = 1; return a })()") + expect(rejection(taggedArray)).toContain('symbol-keyed') + }) + + it('rejects non-finite numbers and undefined values inside containers', () => { + expect(rejection(inRealm('{ n: NaN }'))).toContain('non-finite') + expect(rejection(inRealm('[Infinity]'))).toContain('non-finite') + }) + + it('rejects exotic prototypes (Date, Map, class instances) but accepts null-prototype data', () => { + expect(rejection(inRealm('{ d: new Date(0) }'))).toContain('exotic prototype') + expect(rejection(inRealm('new Map()'))).toContain('exotic prototype') + expect(rejection(inRealm('(() => { class C { constructor() { this.x = 1 } } return new C() })()'))) + .toContain('exotic prototype') + expect(materializeFromRealm(inRealm('Object.assign(Object.create(null), { a: 1 })'))).toEqual({ a: 1 }) + }) + + it('rejects cycles and accepts the same object reused as a sibling (a DAG)', () => { + expect(rejection(inRealm('(() => { const o = {}; o.self = o; return o })()'))).toContain('circular') + const dag = inRealm('(() => { const leaf = { v: 1 }; return { a: leaf, b: leaf } })()') + expect(materializeFromRealm(dag)).toEqual({ a: { v: 1 }, b: { v: 1 } }) + }) + + it('rejects sparse arrays, accessor elements, and non-index array properties', () => { + expect(rejection(inRealm('[1, , 3]'))).toContain('sparse') + expect(rejection(inRealm('(() => { const a = [1]; Object.defineProperty(a, 0, { get: () => 1 }); return a })()'))) + .toContain('accessor') + expect(rejection(inRealm('(() => { const a = [1]; a.total = 3; return a })()'))) + .toContain('non-index') + }) + + it('skips non-enumerable own properties (matching JSON.stringify exactly)', () => { + const value = inRealm(`(() => { + const o = { visible: 1 } + Object.defineProperty(o, 'hidden', { value: () => 1, enumerable: false }) + return o + })()`) + expect(materializeFromRealm(value)).toEqual({ visible: 1 }) + }) + + it('works on plain host values too (the boundary is realm-agnostic)', () => { + expect(materializeFromRealm({ a: [1, 'x'] })).toEqual({ a: [1, 'x'] }) + expect(materializeFromRealm('str')).toBe('str') + expect(materializeFromRealm(3)).toBe(3) + expect(materializeFromRealm(false)).toBe(false) + expect(materializeFromRealm(null)).toBeNull() + }) +}) diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts new file mode 100644 index 0000000000..9403dc912e --- /dev/null +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -0,0 +1,614 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import { AgentId } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import SubagentService from '@deepseek-ai/dsh-subagent' +import type { SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent' +import type { WorkflowResult, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' +import * as vmEngineModule from '../src/index.ts' +import VmWorkflowEngine, { type Config } from '../src/index.ts' + +/** A minimal parent stand-in: the engine only threads it through to the provider. */ +function fakeParent(): Agent { + return { id: AgentId('workflow-parent'), options: {} } as unknown as Agent +} + +/** One controllable child run: the test (or auto mode) settles it. */ +interface ControlledRun { + request: SubagentStartRequest + settle(result: SubagentResult): void + cancelled: string | undefined + disposed: boolean +} + +/** + * A scripted in-test provider over the REAL SubagentService registry: `auto` + * settles each run via the reply function on a microtask; `manual` piles runs + * up in `runs` for the test to settle (concurrency/cancellation tests). A run + * aborts (settles `aborted`) when the request signal fires, like the real + * in-process backends. + */ +class StubProvider implements SubagentProvider { + readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true } + readonly runs: ControlledRun[] = [] + + constructor( + readonly name: string, + private readonly reply?: (request: SubagentStartRequest, index: number) => SubagentResult, + ) {} + + start(request: SubagentStartRequest): SubagentRun { + let settle!: (result: SubagentResult) => void + const result = new Promise((resolve) => { settle = resolve }) + const controlled: ControlledRun = { request, settle, cancelled: undefined, disposed: false } + this.runs.push(controlled) + const index = this.runs.length - 1 + request.signal?.addEventListener('abort', () => { settle({ output: [], stopReason: 'aborted' }) }, { once: true }) + if (this.reply) { + const reply = this.reply + queueMicrotask(() => { settle(reply(request, index)) }) + } + return { + id: AgentId(`stub-child-${index}`), + result, + cancel: (reason?: string) => { + controlled.cancelled = reason ?? 'cancelled' + settle({ output: [], stopReason: 'aborted' }) + }, + dispose: () => { + controlled.disposed = true + return Promise.resolve() + }, + } + } +} + +/** Text-reply helper for auto providers. */ +function text(reply: string): SubagentResult { + return { output: [{ type: 'text', text: reply }], stopReason: 'completed' } +} + +interface SetupOptions { + config?: Config + reply?: (request: SubagentStartRequest, index: number) => SubagentResult + manual?: boolean +} + +async function setup(options?: SetupOptions) { + const ctx = new Context() + await ctx.plugin(SubagentService) + const provider = new StubProvider('stub', options?.manual ? undefined : options?.reply ?? (() => text('stub reply'))) + ctx.subagents.registerProvider(provider) + await ctx.plugin(VmWorkflowEngine, { provider: 'stub', ...options?.config }) + return { ctx, provider, parent: fakeParent() } +} + +/** Wrap a body in the minimal valid meta header. */ +function script(body: string, metaExtra = ''): string { + return `export const meta = { name: 'test-flow', description: 'a test workflow'${metaExtra} }\n${body}` +} + +/** Start + await one run, disposing on the way out. */ +async function run(ctx: Context, parent: Agent, source: string, args?: unknown): Promise { + const handle = ctx.workflows.start({ script: source, parent, ...args !== undefined ? { args } : {} }) + try { + return await handle.result + } finally { + await handle.dispose() + } +} + +describe('dsh-workflow-vm', () => { + describe('script execution', () => { + it('runs a script end-to-end: agent() text results, phases, log, args, return value', async () => { + const { ctx, parent, provider } = await setup({ reply: (_request, index) => text(`answer-${index}`) }) + const events: [string, unknown[]][] = [] + for (const name of ['workflow/start', 'workflow/phase', 'workflow/log', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) { + ctx.on(name, (...payload: unknown[]) => { events.push([name, payload]) }) + } + const result = await run(ctx, parent, script(` + phase('Scan') + log('starting with ' + args.files.length + ' files') + const answers = await pipeline(args.files, (prev, item) => agent('read ' + item)) + phase('Report') + return { answers, count: args.files.length } + `, ", phases: [{ title: 'Scan' }, { title: 'Report' }]"), { files: ['a.ts', 'b.ts'] }) + + expect(result.stopReason).toBe('completed') + expect(result.agentsStarted).toBe(2) + expect(result.value).toEqual({ answers: ['answer-0', 'answer-1'], count: 2 }) + expect(provider.runs.every(r => r.disposed)).toBe(true) + + const names = events.map(([name]) => name) + expect(names[0]).toBe('workflow/start') + expect(names).toContain('workflow/phase') + expect(names).toContain('workflow/log') + expect(names.at(-1)).toBe('workflow/end') + const info = events[0]![1][0] as WorkflowRunInfo + expect(info.meta.name).toBe('test-flow') + const end = events.at(-1)![1][1] as Record + expect(end).toEqual({ stopReason: 'completed', agentsStarted: 2 }) + expect('value' in end).toBe(false) + }) + + it('agent-start/end events carry seq, label (defaulted from the prompt), phase, and outcome', async () => { + const { ctx, parent } = await setup() + const starts: unknown[] = [] + const ends: unknown[] = [] + ctx.on('workflow/agent-start', (_info, agent) => starts.push(agent)) + ctx.on('workflow/agent-end', (_info, agent) => ends.push(agent)) + await run(ctx, parent, script(` + phase('Find') + await agent('a prompt that is quite long and will surely get truncated down to a display label\\n' + + 'with a second line the label must not include') + await agent('short', { label: 'named', phase: 'Custom' }) + return null + `)) + expect(starts[0]).toMatchObject({ seq: 1, phase: 'Find', childId: 'stub-child-0' }) + expect((starts[0] as { label: string }).label.length).toBeLessThanOrEqual(48) + expect((starts[0] as { label: string }).label).not.toContain('second line') + expect(starts[1]).toMatchObject({ seq: 2, label: 'named', phase: 'Custom' }) + expect(ends[0]).toMatchObject({ seq: 1, outcome: 'completed' }) + }) + + it('agent({schema}) forwards outputSchema to the provider and returns the structured value into the realm', async () => { + const { ctx, parent, provider } = await setup({ + reply: () => ({ output: [], structured: { files: ['x.ts', 'y.ts'] }, stopReason: 'completed' }), + }) + const result = await run(ctx, parent, script(` + const found = await agent('list files', { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'] } }) + return { first: found.files[0], count: found.files.length } + `)) + expect(result.value).toEqual({ first: 'x.ts', count: 2 }) + expect(provider.runs[0]!.request.outputSchema).toEqual({ + type: 'object', + properties: { files: { type: 'array', items: { type: 'string' } } }, + required: ['files'], + }) + }) + + it('model option maps to agentOptions.model on the start request', async () => { + const { ctx, parent, provider } = await setup() + await run(ctx, parent, script("return await agent('p', { model: 'deepseek-v4-pro' })")) + expect(provider.runs[0]!.request.agentOptions).toEqual({ model: 'deepseek-v4-pro' }) + }) + + it('a failed child resolves null (scripts filter), never throwing into the script', async () => { + const { ctx, parent } = await setup({ + reply: (_request, index) => index === 0 ? { output: [], stopReason: 'error' } : text('ok'), + }) + const result = await run(ctx, parent, script(` + const results = await parallel([() => agent('one'), () => agent('two')]) + return results + `)) + expect(result.value).toEqual([null, 'ok']) + }) + + it('a schema run that completes WITHOUT a structured value is a child failure (null + failed outcome)', async () => { + const { ctx, parent } = await setup({ reply: () => text('prose, no structure') }) + const ends: unknown[] = [] + ctx.on('workflow/agent-end', (_info, agent) => ends.push(agent)) + const result = await run(ctx, parent, script(` + return await agent('p', { schema: { type: 'object' } }) + `)) + expect(result.value).toBeNull() + expect(ends[0]).toMatchObject({ outcome: 'failed' }) + }) + + it('a script with no return value resolves value: null', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script("await agent('p')")) + expect(result.stopReason).toBe('completed') + expect(result.value).toBeNull() + }) + }) + + describe('combinator semantics', () => { + it('pipeline has NO cross-stage barrier: a fast item finishes stage 2 while a slow item holds stage 1', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + script: script(` + const out = await pipeline(['slow', 'fast'], + (prev, item) => agent('s1 ' + item), + (prev, item) => agent('s2 ' + item + ' after ' + prev), + ) + return out + `), + parent: fakeParent(), + }) + // Both items enter stage 1 concurrently. + await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + // Settle only the FAST item's stage 1 → its stage 2 starts with no barrier. + provider.runs[1]!.settle(text('fast-1')) + await vi.waitFor(() => { expect(provider.runs.length).toBe(3) }) + expect((provider.runs[2]!.request.prompt[0] as { text: string }).text).toBe('s2 fast after fast-1') + // The slow item is still sitting in stage 1. + provider.runs[2]!.settle(text('fast-2')) + provider.runs[0]!.settle(text('slow-1')) + await vi.waitFor(() => { expect(provider.runs.length).toBe(4) }) + provider.runs[3]!.settle(text('slow-2')) + const result = await handle.result + expect(result.value).toEqual(['slow-2', 'fast-2']) + await handle.dispose() + void parent + }) + + it('pipeline stage callbacks receive (prev, item, index); an ordinary stage throw nulls the ITEM and skips its remaining stages', async () => { + const { ctx, parent, provider } = await setup({ reply: request => text(`ok:${(request.prompt[0] as { text: string }).text}`) }) + const result = await run(ctx, parent, script(` + const out = await pipeline([10, 20], + (prev, item, index) => { + if (item === 10) throw new Error('ordinary failure') + return agent('stage1-' + item + '-' + index) + }, + (prev) => agent('stage2 saw ' + prev), + ) + return out + `)) + expect(result.stopReason).toBe('completed') + const prompts = provider.runs.map(r => (r.request.prompt[0] as { text: string }).text) + // Item 10 never reached stage 1's agent nor stage 2. + expect(prompts).toEqual(['stage1-20-1', 'stage2 saw ok:stage1-20-1']) + expect(result.value).toEqual([null, 'ok:stage2 saw ok:stage1-20-1']) + }) + + it('parallel maps a throwing thunk to null and never rejects for ordinary errors', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + return await parallel([ + () => { throw new Error('boom') }, + () => agent('fine'), + () => 'plain value', + ]) + `)) + expect(result.value).toEqual([null, 'stub reply', 'plain value']) + }) + + it('FATAL errors propagate through parallel AND pipeline instead of dissolving into null', async () => { + const { ctx, parent } = await setup() + const viaParallel = await run(ctx, parent, script(` + return await parallel([() => agent('x', { isolation: 'worktree' })]) + `)) + expect(viaParallel.stopReason).toBe('error') + expect(viaParallel.error).toContain('"isolation" is deferred') + + const viaPipeline = await run(ctx, parent, script(` + return await pipeline([1], () => agent('x', { bogus: true })) + `)) + expect(viaPipeline.stopReason).toBe('error') + expect(viaPipeline.error).toContain('"bogus" is not recognized') + }) + + it('validates combinator arguments loudly (non-array, non-function, missing stages)', async () => { + const { ctx, parent } = await setup() + expect((await run(ctx, parent, script("return await parallel('no')"))).error).toContain('parallel() requires an array') + expect((await run(ctx, parent, script('return await parallel([3])'))).error).toContain('item 0 is not a function') + expect((await run(ctx, parent, script("return await pipeline('no', () => 1)"))).error).toContain('pipeline() requires an items array') + expect((await run(ctx, parent, script('return await pipeline([1])'))).error).toContain('at least one stage') + expect((await run(ctx, parent, script("return await pipeline([1], 'x')"))).error).toContain('stage 0 is not a function') + }) + }) + + describe('caps and option validation', () => { + it('trips the total-agent cap with a message naming the config knob', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', maxTotalAgents: 2 } }) + const result = await run(ctx, parent, script(` + await agent('1'); await agent('2'); await agent('3') + return 'unreachable' + `)) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('total agent cap (2)') + expect(result.error).toContain('maxTotalAgents') + expect(result.agentsStarted).toBe(2) + }) + + it('trips the per-call item cap for parallel and pipeline', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', maxItemsPerCall: 2 } }) + expect((await run(ctx, parent, script('return await parallel([() => 1, () => 2, () => 3])'))).error) + .toContain('over the per-call cap (2)') + expect((await run(ctx, parent, script('return await pipeline([1, 2, 3], (x) => x)'))).error) + .toContain('maxItemsPerCall') + }) + + it('enforces the concurrency ceiling: never more than maxConcurrentAgents children in flight', async () => { + const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 2 } }) + const handle = ctx.workflows.start({ + script: script("return await parallel([1, 2, 3, 4, 5].map((n) => () => agent('job ' + n)))"), + parent, + }) + // Only 2 children may exist until one settles. + await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + await new Promise(resolve => setTimeout(resolve, 20)) + expect(provider.runs.length).toBe(2) + // Settle children in arrival order; after each settle at most ONE more + // child may enter — the window never exceeds the ceiling. + for (let index = 0; index < 5; index++) { + await vi.waitFor(() => { expect(provider.runs.length).toBeGreaterThan(index) }) + expect(provider.runs.length).toBeLessThanOrEqual(Math.min(index + 2, 5)) + provider.runs[index]!.settle(text(`r${index}`)) + } + const result = await handle.result + expect(result.stopReason).toBe('completed') + expect(result.agentsStarted).toBe(5) + expect(result.value).toEqual(['r0', 'r1', 'r2', 'r3', 'r4']) + await handle.dispose() + }) + + it('rejects malformed agent() arguments and option types loudly', async () => { + const { ctx, parent } = await setup() + expect((await run(ctx, parent, script('return await agent(42)'))).error).toContain('non-empty prompt string') + expect((await run(ctx, parent, script("return await agent('')"))).error).toContain('non-empty prompt string') + expect((await run(ctx, parent, script("return await agent('p', 'opts')"))).error).toContain('options must be an object') + expect((await run(ctx, parent, script("return await agent('p', { label: 3 })"))).error).toContain('"label" must be a string') + expect((await run(ctx, parent, script("return await agent('p', { effort: 'high' })"))).error).toContain('"effort" is deferred') + }) + + it('rejects options that are not plain JSON data (an accessor smuggled into opts)', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script("return await agent('p', { get label() { return 'x' } })")) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('options must be plain JSON data') + }) + + it('validates phase() and log() arguments loudly', async () => { + const { ctx, parent } = await setup() + expect((await run(ctx, parent, script('phase(3)'))).error).toContain('phase() requires a non-empty title string') + expect((await run(ctx, parent, script("phase('')"))).error).toContain('phase() requires a non-empty title string') + expect((await run(ctx, parent, script('log(3)'))).error).toContain('log() requires a message string') + }) + + it('rejects an unsupported schema via the shared subset assertion (UNSUPPORTED_SCHEMA)', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script("return await agent('p', { schema: { type: 'object', oneOf: [] } })")) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('outside the supported subset') + expect(result.error).toContain('oneOf') + }) + + it('wraps a provider start failure as a fatal AGENT_START error (a missing provider cannot dissolve into null)', async () => { + const { ctx, parent } = await setup({ config: { provider: 'nonexistent' } }) + const result = await run(ctx, parent, script("return await pipeline([1], () => agent('p'))")) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('could not start a child on provider "nonexistent"') + }) + }) + + describe('determinism bans and realm isolation', () => { + it('Date.now, Math.random, and argless new Date throw; parameterized Date stays usable', async () => { + const { ctx, parent } = await setup() + expect((await run(ctx, parent, script('return Date.now()'))).error).toContain('Date.now() is not available') + expect((await run(ctx, parent, script('return Math.random()'))).error).toContain('Math.random() is not available') + expect((await run(ctx, parent, script('return new Date().toISOString()'))).error).toContain('argless new Date()') + const ok = await run(ctx, parent, script('return new Date(0).getTime()')) + expect(ok.value).toBe(0) + }) + + it('args cross into the realm as data: mutating them (or their prototype chain) cannot reach host intrinsics', async () => { + const { ctx, parent } = await setup() + const hostArgs = { files: ['a.ts'], nested: { deep: [1, 2] } } + const result = await run(ctx, parent, script(` + args.files.push('b.ts') + Object.getPrototypeOf(args).polluted = 'realm-only' + return { count: args.files.length, deep: args.nested.deep[1] } + `), hostArgs) + expect(result.value).toEqual({ count: 2, deep: 2 }) + // The host copy is untouched, and the HOST Object.prototype was never reachable. + expect(hostArgs.files).toEqual(['a.ts']) + expect(({} as Record).polluted).toBeUndefined() + }) + + it('scalar/null args pass through directly; absent args leave the global undefined', async () => { + const { ctx, parent } = await setup() + expect((await run(ctx, parent, script('return args * 2'), 21)).value).toBe(42) + expect((await run(ctx, parent, script('return args === null'), null)).value).toBe(true) + expect((await run(ctx, parent, script('return typeof args'))).value).toBe('undefined') + }) + + it('a non-JSON return value fails loud as RESULT_UNSERIALIZABLE', async () => { + const { ctx, parent } = await setup() + const withDate = await run(ctx, parent, script('return { when: new Date(0) }')) + expect(withDate.stopReason).toBe('error') + expect(withDate.error).toContain('not plain JSON data') + const withFn = await run(ctx, parent, script('return { fn: () => 1 }')) + expect(withFn.error).toContain('not plain JSON data') + }) + + it('kills a synchronous spin in the initial slice via the vm timeout', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', syncTimeoutMs: 50 } }) + const result = await run(ctx, parent, script('while (true) {}')) + expect(result.stopReason).toBe('error') + expect(result.error?.toLowerCase()).toContain('timed out') + }) + }) + + describe('lifecycle: parse errors, cancellation, disposal', () => { + it('start() throws synchronously for an unparseable script or invalid meta', async () => { + const { ctx, parent } = await setup() + expect(() => ctx.workflows.start({ script: 'const x = 1', parent })).toThrow(/must begin with/) + expect(() => ctx.workflows.start({ script: script('return ((('), parent })).toThrow(/does not parse/) + }) + + it('cancel() aborts in-flight children and settles the run cancelled', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ script: script("return await agent('long job')"), parent }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + handle.cancel('user stopped it') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('user stopped it') + expect(provider.runs[0]!.disposed).toBe(true) + await handle.dispose() + }) + + it('an already-aborted request signal cancels before any child starts', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const controller = new AbortController() + controller.abort() + const handle = ctx.workflows.start({ script: script("return await agent('never')"), parent, signal: controller.signal }) + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(provider.runs.length).toBe(0) + await handle.dispose() + }) + + it('the signal aborting mid-run cancels like cancel()', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const controller = new AbortController() + const handle = ctx.workflows.start({ script: script("return await agent('job')"), parent, signal: controller.signal }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + controller.abort() + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + await handle.dispose() + }) + + it('reports a non-Error script throw (a thrown string) faithfully', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script("throw 'plain string failure'")) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('plain string failure') + }) + + it('a script Error surfaces its stack, carrying the script line numbers (lineOffset)', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script("throw new Error('with stack')")) + expect(result.stopReason).toBe('error') + // Line 1 is the blanked meta statement; the throw sits on line 2. + expect(result.error).toContain('workflow:test-flow:2') + }) + + it('an object throw with neither stack nor message stringifies', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script('throw { code: 42 }')) + expect(result.stopReason).toBe('error') + expect(result.error).toBe('[object Object]') + }) + + it('falls back to the message for an Error whose stack was stripped', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + const e = new Error('stackless failure') + e.stack = undefined + throw e + `)) + expect(result.stopReason).toBe('error') + expect(result.error).toBe('stackless failure') + }) + + it('a waiter resumed by a release RACING a cancel still dies at the post-acquire check', async () => { + const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 1 } }) + const handle = ctx.workflows.start({ + script: script("return await parallel([() => agent('a'), () => agent('b')])"), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + // Same synchronous block: the release resolves b's waiter, then the + // cancel lands BEFORE b's continuation runs — b must not start a child. + provider.runs[0]!.settle(text('a-done')) + handle.cancel('raced') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(provider.runs.length).toBe(1) + await handle.dispose() + }) + + it('a dropped agent() promise cannot become an unhandled rejection when cancellation lands', async () => { + const unhandled: unknown[] = [] + const onUnhandled = (reason: unknown): void => { unhandled.push(reason) } + process.on('unhandledRejection', onUnhandled) + try { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + script: script(` + agent('dropped, never awaited') + return await agent('awaited') + `), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + handle.cancel() + await handle.result + await handle.dispose() + // Let any stray rejection reach the process hook before asserting. + await new Promise(resolve => setTimeout(resolve, 20)) + expect(unhandled).toEqual([]) + } finally { + process.off('unhandledRejection', onUnhandled) + } + }) + + it('dispose() abandons a stuck script after the grace instead of hanging (result stays pending)', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) + const handle = ctx.workflows.start({ + // No hooks involved: an unsettleable await the engine cannot reject. + script: script("await new Promise(() => {})\nreturn 'unreachable'"), + parent, + }) + const before = Date.now() + await handle.dispose() + expect(Date.now() - before).toBeLessThan(1000) + const settled = await Promise.race([handle.result.then(() => 'settled'), Promise.resolve('pending')]) + expect(settled).toBe('pending') + }) + + it('dispose() is idempotent and settles cleanly after a completed run', async () => { + const { ctx, parent } = await setup() + const handle = ctx.workflows.start({ script: script('return 1'), parent }) + await handle.result + await handle.dispose() + await handle.dispose() + }) + + it('strays: children fired without await are aborted once the script settles', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + script: script(` + agent('stray') + return 'done without awaiting' + `), + parent, + }) + const result = await handle.result + expect(result.stopReason).toBe('completed') + await vi.waitFor(() => { + expect(provider.runs.length).toBe(1) + expect(provider.runs[0]!.disposed).toBe(true) + }) + await handle.dispose() + }) + }) + + describe('service surface', () => { + it('run ids are unique per start; the run handle and event payloads hold SEPARATE meta clones', async () => { + const { ctx, parent } = await setup() + let eventMeta: WorkflowRunInfo | undefined + ctx.on('workflow/start', (info) => { eventMeta = info }) + const first = ctx.workflows.start({ script: script('return 1'), parent }) + const second = ctx.workflows.start({ script: script('return 2'), parent }) + expect(first.id).not.toBe(second.id) + // Mutating a listener's snapshot cannot corrupt the holder's view. + eventMeta!.meta.name = 'corrupted' + expect(second.meta.name).toBe('test-flow') + await Promise.all([first.result, second.result]) + await first.dispose() + await second.dispose() + }) + + it('unregisters ctx.workflows when the engine fiber is disposed (HMR safety)', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + const fiber = await ctx.plugin(VmWorkflowEngine, {}) + expect(ctx.get('workflows')).toBeDefined() + await fiber.dispose() + expect(ctx.get('workflows')).toBeUndefined() + }) + + it('has the class-plugin export shape (default = the engine service class)', () => { + expect(vmEngineModule.default).toBe(VmWorkflowEngine) + const loader = Object.create(Loader.prototype) as Loader + const unwrapped: unknown = loader.unwrapExports(vmEngineModule) + expect(unwrapped).toBe(VmWorkflowEngine) + }) + }) +}) diff --git a/packages/workflow/workflow-vm/tests/workflow.e2e.ts b/packages/workflow/workflow-vm/tests/workflow.e2e.ts new file mode 100644 index 0000000000..6ddfdb7251 --- /dev/null +++ b/packages/workflow/workflow-vm/tests/workflow.e2e.ts @@ -0,0 +1,131 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' +import SubagentService from '@deepseek-ai/dsh-subagent' +import * as Spawn from '@deepseek-ai/dsh-subagent-spawn' +import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow' +import { CallId } from '@deepseek-ai/dsh-llm' +import VmWorkflowEngine from '../src/index.ts' + +/** + * With-key e2e for the workflow engine: a REAL script drives REAL spawn + * children against the live DeepSeek API — one plain child and one schema'd + * child through the real structured-output runtime — and the run's value, + * events, and child sessions are asserted from the outside (never the + * script's self-report alone). Key-gated (self-skips without + * DEEPSEEK_API_KEY). + */ + +let ctx: Context | undefined + +afterEach(async () => { + await ctx?.fiber.dispose() + ctx = undefined +}) + +async function harness(): Promise { + const built = new Context() + await built.plugin(LlmService) + await built.plugin(SessionStore) + await built.plugin(SystemPrompt) + await built.plugin(ToolRegistry) + await built.plugin(AgentRegistry) + await built.plugin(AgentLoop, { agents: [] }) + await built.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] }) + await built.plugin(SubagentService) + await built.plugin(Spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) + await built.plugin(VmWorkflowEngine, { provider: 'spawn' }) + await built.plugin(ToolWorkflow, {}) + return built +} + +const SCRIPT = `export const meta = { + name: 'e2e-arithmetic', + description: 'two real children: one prose, one structured', + phases: [{ title: 'Ask' }, { title: 'Judge' }], +} +phase('Ask') +log('asking the prose child') +const prose = await agent('Reply with exactly one short sentence: what is 2 + 2?') +phase('Judge') +const judged = await agent( + 'Here is an answer to the question "what is 2+2": ' + prose + + ' — report whether it contains the number 4 and your confidence between 0 and 1.', + { schema: { type: 'object', properties: { containsFour: { type: 'boolean' }, confidence: { type: 'number' } }, required: ['containsFour'] } }, +) +return { prose, containsFour: judged === null ? null : judged.containsFour }` + +describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workflow engine with-key e2e', () => { + it('runs a two-phase script over real children, one through the structured runtime', async () => { + ctx = await harness() + const parentHandle = ctx.agents.create({ + agentId: AgentId('wf-e2e-parent'), + sessionId: 'wf-e2e-session' as never, + agentOptions: { model: 'deepseek-v4-flash' }, + }) + + const events: string[] = [] + const childIds: string[] = [] + for (const name of ['workflow/start', 'workflow/phase', 'workflow/log', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) { + ctx.on(name, (...payload: unknown[]) => { + events.push(name) + if (name === 'workflow/agent-start') childIds.push((payload[1] as { childId: string }).childId) + }) + } + + const run = ctx.workflows.start({ script: SCRIPT, parent: parentHandle.agent }) + const result = await run.result + await run.dispose() + + expect(result.stopReason).toBe('completed') + expect(result.agentsStarted).toBe(2) + const value = result.value as { prose: string; containsFour: boolean | null } + // World checks: the prose child really answered (a real completion), and + // the structured child judged it against the REAL schema-forced tool. + expect(value.prose.length).toBeGreaterThan(0) + expect(value.containsFour).toBe(true) + + expect(events[0]).toBe('workflow/start') + expect(events.at(-1)).toBe('workflow/end') + expect(events.filter(name => name === 'workflow/phase').length).toBe(2) + expect(events.filter(name => name === 'workflow/agent-start').length).toBe(2) + expect(childIds.length).toBe(2) + // The children were disposed to quiescence after collection. + for (const childId of childIds) { + expect(ctx.agents.get(AgentId(childId))).toBeUndefined() + } + await parentHandle.dispose() + }, 240_000) + + it('the workflow TOOL runs the same path through the real registry pipeline', async () => { + ctx = await harness() + const parentHandle = ctx.agents.create({ + agentId: AgentId('wf-e2e-tool-parent'), + sessionId: 'wf-e2e-tool-session' as never, + agentOptions: { model: 'deepseek-v4-flash' }, + }) + + const result = await ctx.tools.execute({ + callId: CallId('wf-e2e-call'), + name: 'workflow', + arguments: { + script: `export const meta = { name: 'e2e-tool', description: 'one real child via the tool' } +const answer = await agent('Reply with exactly one word: the capital of France.') +return { answer }`, + }, + agent: parentHandle.agent, + }) + + expect(result.isError).toBe(false) + const text = (result.content[0] as { text: string }).text + expect(text).toContain('workflow "e2e-tool" completed (1 agent)') + expect(text.toLowerCase()).toContain('paris') + await parentHandle.dispose() + }, 240_000) +}) diff --git a/packages/workflow/workflow-vm/tsconfig.json b/packages/workflow/workflow-vm/tsconfig.json new file mode 100644 index 0000000000..385651c192 --- /dev/null +++ b/packages/workflow/workflow-vm/tsconfig.json @@ -0,0 +1,39 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../subagent/subagent" + }, + { + "path": "../../core/tools" + }, + { + "path": "../workflow" + } + ] +} diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md new file mode 100644 index 0000000000..1dece68d38 --- /dev/null +++ b/packages/workflow/workflow/README.md @@ -0,0 +1,29 @@ +# @deepseek-ai/dsh-workflow + +The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-vm`](../workflow-vm/README.md) is the first, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer. + +## Service: `WorkflowService` (abstract) + +`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). `dispose()` must reach quiescence within a bounded grace (cancel → wait → abandon), never hanging its caller. + +The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment (a throwing subscriber is logged, never propagated, and cannot starve later listeners) — the same guarantee as the subagent seam's lifecycle emits. + +## Vocabulary + +- `WorkflowStartRequest` — `{ script, args?, parent: Agent, signal? }`. `parent` is REQUIRED: every child the script spawns is attributed to it. `args` must be plain host-realm JSON data. +- `WorkflowMeta` / `WorkflowPhase` — the script's validated `export const meta` block (Claude Code format: required `name`/`description`, optional `whenToUse`/`phases`). +- `WorkflowRun` — `{ id, meta, result, cancel(reason?), dispose() }`; the consumer awaits `result` and MUST `dispose` on every path. +- `WorkflowResult` — `{ value, stopReason: 'completed'|'cancelled'|'error', error?, agentsStarted }`; `value` is the script's materialized return (plain JSON data; `null` for no return). +- `WorkflowError` — `HarnessError` with a `WorkflowErrorCode` and a `fatal` flag driving the combinator discipline: a fatal error (bad hook arguments, unsupported options/schemas, tripped caps, seam start failures, cancellation) always propagates through `parallel()`/`pipeline()` instead of dissolving into a per-item `null`. `isFatalWorkflowError(error)` is the catch-site predicate. + +## Events + +All observe-only emits carrying DATA SNAPSHOTS (`WorkflowRunInfo` = id + meta) — never the live `WorkflowRun`, so a listener cannot gain `cancel`/`dispose`; control stays with the `start()` caller: + +- `workflow/start`(info) / `workflow/end`(info, resultInfo) — run lifecycle; `resultInfo` deliberately omits the value. +- `workflow/phase`(info, title) / `workflow/log`(info, message) — script narration. +- `workflow/agent-start`(info, agent) / `workflow/agent-end`(info, agent + outcome) — one pair per `agent()` call, correlated by `seq`. + +## Non-goals (this cut) + +Background collection, journaling/resume, saved workflows, nested `workflow()`, token budgets — see the [RFC's deferred section](../../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md). diff --git a/packages/workflow/workflow/package.json b/packages/workflow/workflow/package.json new file mode 100644 index 0000000000..a6c004d6d0 --- /dev/null +++ b/packages/workflow/workflow/package.json @@ -0,0 +1,37 @@ +{ + "name": "@deepseek-ai/dsh-workflow", + "description": "Workflow capability seam: ctx.workflows service, run vocabulary, and workflow/* events", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts new file mode 100644 index 0000000000..ab5e056b37 --- /dev/null +++ b/packages/workflow/workflow/src/index.ts @@ -0,0 +1,224 @@ +/** + * The workflow capability seam (`ctx.workflows`): an abstract service defining + * WHAT a workflow engine does — execute a model-written orchestration script + * that fans out subagents — without saying HOW. Implementations subclass + * {@link WorkflowService} and register as the `workflows` service (one + * implementation per context, cordis' standard duplicate-service behavior); + * `@deepseek-ai/dsh-workflow-vm` (an in-process `node:vm` engine) is the + * first. Future engines (a worker-thread or isolated-vm sandbox) swap in + * without touching the model-facing tool that consumes them + * (`@deepseek-ai/dsh-tool-workflow`). + * + * The `workflow/*` lifecycle events are OBSERVE-ONLY data snapshots: they + * carry {@link WorkflowRunInfo} (id + meta), never the live {@link WorkflowRun} + * — a listener must not gain `cancel`/`dispose`; control stays with the + * `start()` caller holding the run. Every emit is per-listener contained (a + * throwing subscriber is logged, never propagated), so one bad observer can + * neither strand a live run nor starve later listeners. + * + * @module @deepseek-ai/dsh-workflow + */ + +import { Context, Service } from 'cordis' +import { HarnessError } from '@deepseek-ai/dsh-llm' +import type { + WorkflowAgentEndInfo, + WorkflowAgentInfo, + WorkflowResultInfo, + WorkflowRun, + WorkflowRunInfo, + WorkflowStartRequest, +} from './types.ts' + +export { WorkflowRunId } from './types.ts' +export type { + WorkflowAgentEndInfo, + WorkflowAgentInfo, + WorkflowAgentOutcome, + WorkflowMeta, + WorkflowPhase, + WorkflowResult, + WorkflowResultInfo, + WorkflowRun, + WorkflowRunInfo, + WorkflowStartRequest, + WorkflowStopReason, +} from './types.ts' + +declare module 'cordis' { + interface Context { + workflows: WorkflowService + } + + interface Events { + /** + * A workflow run started — the script's meta block validated, the body + * about to execute. Paired with {@link Events['workflow/end']}. + * @param info - the run's identity snapshot (id + meta). + * @mode emit + */ + 'workflow/start'(info: WorkflowRunInfo): void + /** + * The script entered a phase (a `phase(title)` call) — progress grouping + * for observers; no execution semantics. + * @param info - the run's identity snapshot. + * @param title - the phase title, verbatim. + * @mode emit + */ + 'workflow/phase'(info: WorkflowRunInfo, title: string): void + /** + * The script emitted a narration line (a `log(message)` call). + * @param info - the run's identity snapshot. + * @param message - the logged message, verbatim. + * @mode emit + */ + 'workflow/log'(info: WorkflowRunInfo, message: string): void + /** + * One `agent()` call started a child run. Paired with + * {@link Events['workflow/agent-end']} by `agent.seq`. + * @param info - the run's identity snapshot. + * @param agent - the call's sequence number, label, phase, and child id. + * @mode emit + */ + 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void + /** + * One `agent()` call settled (clean result, child failure, or run + * cancellation). Paired with {@link Events['workflow/agent-start']}. + * @param info - the run's identity snapshot. + * @param agent - the call identity plus its outcome. + * @mode emit + */ + 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void + /** + * A workflow run settled (any stop reason). Fired when + * {@link WorkflowRun.result} resolves. Paired with + * {@link Events['workflow/start']}. + * @param info - the run's identity snapshot. + * @param result - the outcome data (stop reason, error, agent count) — + * deliberately WITHOUT the result value (see {@link WorkflowResultInfo}). + * @mode emit + */ + 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void + } +} + +/** The full set of `workflow/*` event names {@link WorkflowService.emitWorkflowEvent} dispatches. */ +export type WorkflowEventName = + | 'workflow/start' + | 'workflow/phase' + | 'workflow/log' + | 'workflow/agent-start' + | 'workflow/agent-end' + | 'workflow/end' + +/** + * The workflow-seam error codes. Every one of these is FATAL when it reaches + * a script (see {@link WorkflowError.fatal}): the combinators re-throw it + * instead of dissolving it into an ordinary per-item `null`. + * + * - `SCRIPT_PARSE` — the script (or its meta statement) does not parse. + * - `META_INVALID` — the meta block evaluated but fails the shape contract. + * - `INVALID_ARGUMENT` — a hook was called with malformed arguments. + * - `UNSUPPORTED_OPTION` — an `agent()` option this engine does not support + * (deferred: `effort`/`isolation`/`agentType`) or does not know. + * - `UNSUPPORTED_SCHEMA` — an `agent()` schema outside the structured-output + * subset (see dsh-tools). + * - `AGENT_CAP` / `ITEM_CAP` — the run/agent caps tripped. + * - `AGENT_START` — the subagent seam refused to start a child. + * - `RESULT_UNSERIALIZABLE` — a value crossing the realm boundary is not + * plain JSON data. + * - `CANCELLED` — the run was cancelled; pending and future hooks reject + * with this (the script-kill mechanism). + */ +export type WorkflowErrorCode = + | 'SCRIPT_PARSE' + | 'META_INVALID' + | 'INVALID_ARGUMENT' + | 'UNSUPPORTED_OPTION' + | 'UNSUPPORTED_SCHEMA' + | 'AGENT_CAP' + | 'ITEM_CAP' + | 'AGENT_START' + | 'RESULT_UNSERIALIZABLE' + | 'CANCELLED' + +/** + * Typed error for workflow-seam failures. Extends {@link HarnessError}, so the + * `code` is machine-routable taxonomy. `fatal` drives the combinator + * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd + * option or a tripped cap must kill the script loudly), and reserve the + * per-item `null` for child-run failures and ordinary in-stage script errors. + * Every {@link WorkflowErrorCode} is fatal in this cut; the flag exists so the + * distinction is explicit at every catch site rather than implied. + */ +export class WorkflowError extends HarnessError { + /** Whether combinators must propagate this error instead of nulling the item. */ + readonly fatal: boolean + + constructor(message: string, code: WorkflowErrorCode, options?: ErrorOptions & { fatal?: boolean }) { + super(message, code, options) + this.name = 'WorkflowError' + this.fatal = options?.fatal ?? true + } +} + +/** Whether combinators must re-throw `error` instead of mapping the item to `null`. */ +export function isFatalWorkflowError(error: unknown): boolean { + return error instanceof WorkflowError && error.fatal +} + +/** + * Abstract workflow execution service. Subclass, implement {@link start}, and + * load the subclass as a plugin — it registers as `ctx.workflows` (one + * implementation per context; loading a second throws, cordis' standard + * duplicate-service behavior). + * + * Semantics every implementation must honor: + * - {@link start} throws synchronously for a request that cannot begin (an + * unparseable script, an invalid meta block). Once it returns a + * {@link WorkflowRun}, `result` NEVER rejects — every failure resolves with + * `stopReason: 'error'` (or `'cancelled'`). + * - The `workflow/*` events fire through {@link emitWorkflowEvent} (data + * snapshots, per-listener containment); `workflow/end` fires exactly once + * per started run, after `result` is settled or as it settles. + * - `dispose()` reaches quiescence within a bounded grace: it cancels, waits + * for the script to settle, and abandons a stuck script rather than + * hanging its caller (the engine documents what abandonment leaves behind). + */ +export abstract class WorkflowService extends Service { + constructor(ctx: Context) { + super(ctx, 'workflows') + } + + /** + * Parse and execute a workflow script. + * @param request - the script, its `args`, the parent agent, and an + * optional cancel signal. + * @returns the live run; its `result` resolves when the script settles. + */ + abstract start(request: WorkflowStartRequest): WorkflowRun + + /** + * Emit one `workflow/*` lifecycle event with PER-LISTENER containment: + * dispatch each subscriber individually and log (never propagate) a thrown + * one, so one bad subscriber can neither fail the engine mid-run, surface as + * an unhandled rejection on a detached settle hook, nor starve the listeners + * registered after it (cordis `emit` halts on the first throw — same + * guarantee as the subagent seam's lifecycle emits). + * @param name - the `workflow/*` event to dispatch. + * @param args - the event's payload, matching its declared signature. + */ + protected emitWorkflowEvent(name: WorkflowEventName, ...args: unknown[]): void { + for (const callback of this.ctx.events.dispatch('emit', [name, ...args])) { + try { + // The declared workflow/* signatures are all void-returning emits; the + // dispatch callback applies the payload tuple. + ;(callback as (...payload: unknown[]) => void)(...args) + } catch (error: unknown) { + this.ctx.logger.warn(`workflow: ${name} listener threw: ${String(error)}`) + } + } + } +} + +export default WorkflowService diff --git a/packages/workflow/workflow/src/types.ts b/packages/workflow/workflow/src/types.ts new file mode 100644 index 0000000000..32377ee46b --- /dev/null +++ b/packages/workflow/workflow/src/types.ts @@ -0,0 +1,154 @@ +/** + * Workflow seam vocabulary: the request/run/result types a workflow engine + * consumes and produces, plus the payload shapes of the `workflow/*` events. + * Types only (plus the id-brand factory), per the package convention. + * + * @module @deepseek-ai/dsh-workflow/types + */ + +import type { Branded } from '@deepseek-ai/dsh-brand' +import type { Agent, AgentId } from '@deepseek-ai/dsh-agent' + +/** Identifies one workflow run. */ +export type WorkflowRunId = Branded<'WorkflowRunId'> + +/** Brand a string as a {@link WorkflowRunId}. */ +export function WorkflowRunId(id: string): WorkflowRunId { + return id as WorkflowRunId +} + +/** + * One phase declared in a script's `meta.phases` (progress vocabulary only — + * phases group agents in observers/UIs; they impose no execution structure). + */ +export interface WorkflowPhase { + /** The phase title; `phase()` calls match against it by exact string. */ + title: string + /** Optional one-line description of what the phase does. */ + detail?: string + /** Optional model override this phase is expected to use (informational). */ + model?: string +} + +/** + * The script's `export const meta` block, validated by the engine before the + * body runs. `name`/`description` are required; the rest is optional + * annotation. Matches the Claude Code dynamic-workflows script format. + */ +export interface WorkflowMeta { + /** Short kebab-case workflow name (display + persistence key). */ + name: string + /** One-line description of what the workflow does. */ + description: string + /** Optional guidance on when this workflow applies (shown in listings). */ + whenToUse?: string + /** Optional phase declarations matched by `phase()` calls. */ + phases?: WorkflowPhase[] +} + +/** + * What a caller asks for when starting a workflow run. `parent` is REQUIRED — + * every `agent()` the script spawns is attributed to it (cwd, lineage, depth + * flow through the subagent seam). `args` must be plain host-realm JSON data; + * the engine exposes it to the script as the `args` global. + */ +export interface WorkflowStartRequest { + /** The full script text: `export const meta = {...}` + a plain-JS body. */ + script: string + /** Optional input exposed verbatim to the script as the `args` global. */ + args?: unknown + /** The agent on whose behalf the run executes (parent of every child). */ + parent: Agent + /** Cancels the run when aborted (the tool's `exec.signal`). */ + signal?: AbortSignal +} + +/** + * Why a run settled. CLOSED union (engine-owned, consumers may exhaust): + * `completed` = the script ran to its final `return`; `cancelled` = the run + * was cancelled (caller `cancel()`/signal); `error` = the script threw, a + * fatal `WorkflowError` propagated, or the result failed materialization. + */ +export type WorkflowStopReason = 'completed' | 'cancelled' | 'error' + +/** + * The outcome of one run, resolved by {@link WorkflowRun.result}. `value` is + * the script's materialized return value (plain host-realm JSON data; `null` + * when the script returned `undefined`) — meaningful only for `completed`. + * A non-`completed` reason carries the failure in `error`; the consumer maps + * it to an `isError` tool result rather than reporting partial output. + */ +export interface WorkflowResult { + /** The script's return value (host JSON data; `null` for no return). */ + value: unknown + /** Why the run settled. */ + stopReason: WorkflowStopReason + /** The failure message (present iff `stopReason` is not `completed`). */ + error?: string + /** How many `agent()` calls the run started (across its whole lifetime). */ + agentsStarted: number +} + +/** + * The handle the consumer holds while a script executes. The consumer awaits + * `result`, may `cancel` mid-flight, and MUST `dispose` on every path. + * `result` does NOT reject — a script failure resolves with `stopReason: + * 'error'` — so the consumer maps a non-`completed` reason to an `isError` + * result. `dispose()` cancels, then waits a bounded grace for the script to + * settle before abandoning it (the engine documents the abandonment + * semantics); it never hangs on a stuck script. + */ +export interface WorkflowRun { + readonly id: WorkflowRunId + /** The validated meta block (available before the body runs). */ + readonly meta: WorkflowMeta + readonly result: Promise + /** Cancel the run: children abort, pending hooks reject, the script dies at its next await. */ + cancel(reason?: string): void + /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */ + dispose(): Promise +} + +/** Identifying detail for a run, carried by every `workflow/*` event (a data snapshot, never the live run). */ +export interface WorkflowRunInfo { + /** The run's id. */ + id: WorkflowRunId + /** The run's validated meta block. */ + meta: WorkflowMeta +} + +/** One `agent()` call's identity within a run (the `workflow/agent-start` payload). */ +export interface WorkflowAgentInfo { + /** 1-based sequence number of this `agent()` call within the run. */ + seq: number + /** The display label (the `label` option, or a prompt snippet). */ + label: string + /** The phase this agent belongs to (the `phase` option, else the current `phase()` title). */ + phase?: string + /** The child agent's id on the subagent seam. */ + childId: AgentId +} + +/** How one `agent()` call settled: clean result, child failure (script sees `null`), or run cancellation. */ +export type WorkflowAgentOutcome = 'completed' | 'failed' | 'cancelled' + +/** One `agent()` call's settlement (the `workflow/agent-end` payload). */ +export interface WorkflowAgentEndInfo extends WorkflowAgentInfo { + /** How the call settled. */ + outcome: WorkflowAgentOutcome +} + +/** + * A settled run's outcome as event data (the `workflow/end` payload): the + * {@link WorkflowResult} minus `value` (a listener observing outcomes must not + * receive a mutable alias of the caller's result value; a consumer that needs + * the value holds the run and awaits `result`). + */ +export interface WorkflowResultInfo { + /** Why the run settled. */ + stopReason: WorkflowStopReason + /** The failure message (present iff `stopReason` is not `completed`). */ + error?: string + /** How many `agent()` calls the run started. */ + agentsStarted: number +} diff --git a/packages/workflow/workflow/tests/workflow.spec.ts b/packages/workflow/workflow/tests/workflow.spec.ts new file mode 100644 index 0000000000..a5bd8cd1ed --- /dev/null +++ b/packages/workflow/workflow/tests/workflow.spec.ts @@ -0,0 +1,86 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import WorkflowServiceDefault, { + isFatalWorkflowError, + WorkflowError, + WorkflowRunId, + WorkflowService, +} from '../src/index.ts' +import type { WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '../src/index.ts' + +/** A minimal concrete subclass exposing the protected emit helper for tests. */ +class StubEngine extends WorkflowService { + start(request: WorkflowStartRequest): WorkflowRun { + void request + throw new Error('not under test') + } + + emit(name: Parameters[0], ...args: unknown[]): void { + this.emitWorkflowEvent(name, ...args) + } +} + +const INFO: WorkflowRunInfo = { id: WorkflowRunId('run-1'), meta: { name: 'w', description: 'd' } } + +describe('dsh-workflow (interface)', () => { + it('WorkflowRunId brands a string (identity at runtime)', () => { + expect(WorkflowRunId('abc')).toBe('abc') + }) + + it('WorkflowError carries code + fatal (default true) and reads as a HarnessError', () => { + const error = new WorkflowError('cap hit', 'AGENT_CAP') + expect(error.code).toBe('AGENT_CAP') + expect(error.fatal).toBe(true) + expect(error.name).toBe('WorkflowError') + const soft = new WorkflowError('advisory', 'ITEM_CAP', { fatal: false }) + expect(soft.fatal).toBe(false) + }) + + it('isFatalWorkflowError: true only for a fatal WorkflowError', () => { + expect(isFatalWorkflowError(new WorkflowError('x', 'CANCELLED'))).toBe(true) + expect(isFatalWorkflowError(new WorkflowError('x', 'CANCELLED', { fatal: false }))).toBe(false) + expect(isFatalWorkflowError(new Error('plain'))).toBe(false) + expect(isFatalWorkflowError('string')).toBe(false) + }) + + it('registers as ctx.workflows and unregisters when its fiber is disposed (HMR safety)', async () => { + const ctx = new Context() + const fiber = await ctx.plugin(StubEngine) + expect(ctx.get('workflows')).toBeInstanceOf(StubEngine) + await fiber.dispose() + expect(ctx.get('workflows')).toBeUndefined() + }) + + it('emitWorkflowEvent dispatches to every listener with the payload tuple', async () => { + const ctx = new Context() + await ctx.plugin(StubEngine) + const seen: unknown[][] = [] + ctx.on('workflow/log', (info, message) => { seen.push([info, message]) }) + ctx.on('workflow/agent-start', (info, agent) => { seen.push([info, agent]) }) + const engine = ctx.workflows as StubEngine + engine.emit('workflow/log', INFO, 'hello') + engine.emit('workflow/agent-start', INFO, { seq: 1, label: 'l', childId: 'c' }) + expect(seen).toEqual([ + [INFO, 'hello'], + [INFO, { seq: 1, label: 'l', childId: 'c' }], + ]) + }) + + it('contains a throwing listener PER LISTENER: later listeners still run, nothing propagates', async () => { + const ctx = new Context() + await ctx.plugin(StubEngine) + const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => ctx.logger) + const reached: string[] = [] + ctx.on('workflow/phase', () => { throw new Error('bad listener') }) + ctx.on('workflow/phase', (_info, title) => { reached.push(title) }) + const engine = ctx.workflows as StubEngine + expect(() => { engine.emit('workflow/phase', INFO, 'Scan') }).not.toThrow() + expect(reached).toEqual(['Scan']) + expect(warn).toHaveBeenCalledOnce() + expect(String(warn.mock.calls[0]![0])).toContain('workflow/phase listener threw') + }) + + it('has the expected export surface (default = the abstract service class)', () => { + expect(WorkflowServiceDefault).toBe(WorkflowService) + }) +}) diff --git a/packages/workflow/workflow/tsconfig.json b/packages/workflow/workflow/tsconfig.json new file mode 100644 index 0000000000..6ec42e0bfe --- /dev/null +++ b/packages/workflow/workflow/tsconfig.json @@ -0,0 +1,27 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../llm/llm" + } + ] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 06189862f2..7877dc9fad 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -635,6 +635,12 @@ importers: '@deepseek-ai/dsh-subagent': specifier: workspace:^ version: link:../subagent + '@deepseek-ai/dsh-subagent-fork': + specifier: workspace:^ + version: link:../subagent-fork + '@deepseek-ai/dsh-subagent-spawn': + specifier: workspace:^ + version: link:../subagent-spawn '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt @@ -1039,6 +1045,95 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/workflow/tool-workflow: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + '@deepseek-ai/dsh-workflow': + specifier: workspace:^ + version: link:../workflow + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + + packages/workflow/workflow: + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + + packages/workflow/workflow-vm: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-agent-loop': + specifier: workspace:^ + version: link:../../core/agent-loop + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../support/invariants + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-subagent': + specifier: workspace:^ + version: link:../../subagent/subagent + '@deepseek-ai/dsh-subagent-spawn': + specifier: workspace:^ + version: link:../../subagent/subagent-spawn + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + '@deepseek-ai/dsh-workflow': + specifier: workspace:^ + version: link:../workflow + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + vendor/cordis: dependencies: '@cordisjs/plugin-include': diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 26db66b995..9058427020 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,5 +1,5 @@ { - "AGENTS.md": 1575, + "AGENTS.md": 1590, "docs/AGENTS.md": 1315, "docs/architecture.md": 1890, "docs/defensive-patterns.md": 550, diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 9dd8e0a6e6..ce1fee586a 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -51,6 +51,8 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs' import * as ToolTodo from '@deepseek-ai/dsh-tool-todo' import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent' import * as ToolWeb from '@deepseek-ai/dsh-tool-web' +import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' +import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow' const root = resolve(import.meta.dirname, '..') const OUT = 'docs/tool-catalog/tools.md' @@ -138,6 +140,20 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolTodo) }, }, + { + pkg: '@deepseek-ai/dsh-tool-workflow', + dir: 'tool-workflow', + source: 'packages/workflow/tool-workflow/src/index.ts', + async mount(ctx) { + // The tool injects `workflows`; boot the vm engine over a scripted + // subagent provider to satisfy it. The schema does not depend on which + // provider backs the engine. + await ctx.plugin(SubagentService) + await ctx.plugin(SubagentMock, { name: 'mock' }) + await ctx.plugin(VmWorkflowEngine, { provider: 'mock' }) + await ctx.plugin(ToolWorkflow) + }, + }, { pkg: '@deepseek-ai/dsh-tool-web', dir: 'tool-web', diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index b1c3163782..18927fc884 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1,82 +1,365 @@ { "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source symbol it must match verbatim. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.", "entries": [ - { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "Message", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "MessageSourceMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "FinishReasonMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "GenerateOptions", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "Agent", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "HookContext", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" }, - - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" }, - - { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEventMap", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "TodoItem", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "TurnTriggerMap", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "TurnEndReasonMap", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceNode", "source": "packages/core/session/src/surface.ts" }, - - { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" }, - - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolDefinition", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaProp", "source": "packages/core/tools/src/schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaSpec", "source": "packages/core/tools/src/schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "InferArgs", "source": "packages/core/tools/src/schema.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": "ToolExecutionResult", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "PreToolDecision", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "PostToolDecision", "source": "packages/core/tools/src/index.ts" }, - - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "CollectedOutput", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTask", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTaskRead", "source": "packages/bash/bash/src/types.ts" }, - - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTarget", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTargetKey", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsVersion", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsInfo", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsDirEntry", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteIntent", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteOutcome", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsEditRequest", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsEditOutcome", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsErrorCode", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPolicyExec", "source": "packages/fs/fs-policy/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FileReadOutcome", "source": "packages/fs/tool-fs/src/read-render.ts" }, - - { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" }, - - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentResult", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStopReasonMap", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentRun", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentProvider", "source": "packages/subagent/subagent/src/types.ts" }, - - { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchRequest", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchResult", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchSource", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchRequest", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchResult", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchBody", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebProviderStatus", "source": "packages/web/web/src/types.ts" } + { + "doc": "docs/core-data-structures/core.md", + "symbol": "Branded", + "source": "packages/util/brand/src/index.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ContentBlockMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "Message", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "MessageSourceMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "FinishReasonMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "GenerateOptions", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ToolSchema", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "SessionEvent", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "Agent", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "HookContext", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "PromptDecision", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ContinuationDecision", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "SessionStartSource", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "StreamChunk", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "TokenUsage", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "ContentBlockMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "AppIdentity", + "source": "packages/llm/llm/src/attribution.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SessionEventMap", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "TodoItem", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SessionEvent", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "TurnTriggerMap", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "TurnEndReasonMap", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceEventType", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceOp", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceIntent", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceNode", + "source": "packages/core/session/src/surface.ts" + }, + { + "doc": "docs/core-data-structures/persistence.md", + "symbol": "SessionHeader", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/persistence.md", + "symbol": "CreateSessionOptions", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolDefinition", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "SchemaProp", + "source": "packages/core/tools/src/schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "SchemaSpec", + "source": "packages/core/tools/src/schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "InferArgs", + "source": "packages/core/tools/src/schema.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": "ToolExecutionResult", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "PreToolDecision", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "PostToolDecision", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashExecRequest", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashExecSpec", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashRunResult", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "CollectedOutput", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashTask", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashTaskRead", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsTarget", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsTargetKey", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsVersion", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsInfo", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsDirEntry", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsWriteIntent", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsWriteOutcome", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsEditRequest", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsEditOutcome", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsErrorCode", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsPolicyExec", + "source": "packages/fs/fs-policy/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FileReadOutcome", + "source": "packages/fs/tool-fs/src/read-render.ts" + }, + { + "doc": "docs/core-data-structures/compaction.md", + "symbol": "CompactionResult", + "source": "packages/compact/compact/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentCapabilities", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentStartRequest", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentResult", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentStopReasonMap", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentRun", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentProvider", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebSearchRequest", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebSearchResult", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebSearchSource", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebFetchRequest", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebFetchResult", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebFetchBody", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebProviderStatus", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowStartRequest", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowMeta", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowResult", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowRun", + "source": "packages/workflow/workflow/src/types.ts" + } ] } diff --git a/tsconfig.base.json b/tsconfig.base.json index 40e4dbe728..b21ca2b8b5 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -46,6 +46,7 @@ "./packages/fs/*/src", "./packages/compact/*/src", "./packages/subagent/*/src", + "./packages/workflow/*/src", "./packages/web/*/src", "./packages/todo/*/src", "./packages/hooks/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index b6ba7901f2..93cce8f4b9 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -51,6 +51,9 @@ { "path": "./packages/subagent/subagent-spawn" }, { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, + { "path": "./packages/workflow/workflow" }, + { "path": "./packages/workflow/workflow-vm" }, + { "path": "./packages/workflow/tool-workflow" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, diff --git a/tsconfig.json b/tsconfig.json index 9cd7aa8a6d..ba5ccbac26 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -62,6 +62,9 @@ { "path": "./packages/subagent/subagent-spawn" }, { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, + { "path": "./packages/workflow/workflow" }, + { "path": "./packages/workflow/workflow-vm" }, + { "path": "./packages/workflow/tool-workflow" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, From 0bf50d3469ec464db9e41e88f056c0aa98365e60 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sun, 5 Jul 2026 17:10:42 +0800 Subject: [PATCH 005/119] test: wire user interaction in stdio readline spec --- packages/ui/stdio-agent/tests/readline.spec.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/ui/stdio-agent/tests/readline.spec.ts b/packages/ui/stdio-agent/tests/readline.spec.ts index ae3c480756..a958c435c1 100644 --- a/packages/ui/stdio-agent/tests/readline.spec.ts +++ b/packages/ui/stdio-agent/tests/readline.spec.ts @@ -19,6 +19,7 @@ function fakeContext(): Context { // The UI seeds its label map from the registry at install; this suite only // exercises readline terminal-mode selection, so an empty roster suffices. agents: { list: vi.fn(() => []) }, + userInteraction: { registerProvider: vi.fn(() => vi.fn()) }, } as unknown as Context } From e264a106fdfea5d5c1db8be72058b6f1a16edf99 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 19:04:38 +0800 Subject: [PATCH 006/119] workflow, subagent: fix Codex code-review round-1 blockers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six verified A-findings from the code-stage review, each with a regression test: - parallel()/pipeline() resolved to HOST arrays inside the vm realm, exposing host Array.prototype to scripts; combinator results are now realm-built (in-realm Array.from bound at context setup). - materializeFromRealm ran proxy traps (ownKeys/getOwnPropertyDescriptor/ getPrototypeOf) during the descriptor walk — realm code on the host stack, outside the vm timeout, escaping as raw errors; proxies (root, nested, and in the prototype position) are now rejected trap-free via util.types.isProxy before any inspection. - an already-aborted signal or an immediate cancel() no longer reports 'completed' for a hook-free script: drive() checks cancellation before running the body and again when the script settles. - dispose() now waits (bounded by disposeGraceMs) for stray agent() children to FINISH disposing, not just for the script to settle: every agent() call is tracked and quiesce() drains the in-flight set. - workflow/* event payloads were live mutable aliases shared across emissions; emitWorkflowEvent now hands each listener its own structural clone. - the structured-output turn-continuation veto is now prepend: true, so an earlier-registered force-continue listener cannot short-circuit it. Docs updated in the same change (READMEs, core-data-structures/workflow.md, the dynamic-workflows RFC, regenerated cordis catalogs). --- docs/cordis-catalog/events.md | 12 +- docs/cordis-catalog/services.md | 4 +- docs/core-data-structures/workflow.md | 4 +- .../feature/2026-07-05-dynamic-workflows.md | 6 +- .../subagent/subagent-inprocess/README.md | 2 +- .../subagent-inprocess/src/structured.ts | 12 +- .../tests/structured.spec.ts | 29 ++++ packages/workflow/workflow-vm/README.md | 6 +- packages/workflow/workflow-vm/src/index.ts | 28 +++- packages/workflow/workflow-vm/src/realm.ts | 19 ++- packages/workflow/workflow-vm/src/runtime.ts | 57 ++++++- .../workflow/workflow-vm/tests/meta.spec.ts | 8 + .../workflow/workflow-vm/tests/realm.spec.ts | 21 +++ .../workflow-vm/tests/workflow-vm.spec.ts | 146 +++++++++++++++++- packages/workflow/workflow/README.md | 4 +- packages/workflow/workflow/src/index.ts | 29 ++-- .../workflow/workflow/tests/workflow.spec.ts | 22 +++ 17 files changed, 358 insertions(+), 51 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 463c7e06b2..1ba45f027e 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -323,7 +323,7 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void ``` -Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:93`](../../packages/workflow/workflow/src/index.ts) ### `workflow/agent-start` — emit @@ -333,7 +333,7 @@ One `agent()` call started a child run. Paired with Events['workflow/agent-end'] 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void ``` -Source: [`packages/workflow/workflow/src/index.ts:83`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:85`](../../packages/workflow/workflow/src/index.ts) ### `workflow/end` — emit @@ -343,7 +343,7 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void ``` -Source: [`packages/workflow/workflow/src/index.ts:101`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:103`](../../packages/workflow/workflow/src/index.ts) ### `workflow/log` — emit @@ -353,7 +353,7 @@ The script emitted a narration line (a `log(message)` call). 'workflow/log'(info: WorkflowRunInfo, message: string): void ``` -Source: [`packages/workflow/workflow/src/index.ts:75`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:77`](../../packages/workflow/workflow/src/index.ts) ### `workflow/phase` — emit @@ -363,7 +363,7 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs 'workflow/phase'(info: WorkflowRunInfo, title: string): void ``` -Source: [`packages/workflow/workflow/src/index.ts:68`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts) ### `workflow/start` — emit @@ -373,7 +373,7 @@ A workflow run started — the script's meta block validated, the body about to 'workflow/start'(info: WorkflowRunInfo): void ``` -Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:62`](../../packages/workflow/workflow/src/index.ts) ## Inherited events (cordis core + loader/hmr/timer) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index c1f67c0725..88559d658f 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -235,13 +235,13 @@ Semantics every implementation must honor: - start throws synchronously for a request that cannot begin (an unparseable script, an invalid meta block). Once it returns a WorkflowRun, `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). - The `workflow/*` events fire through emitWorkflowEvent (data snapshots, per-listener containment); `workflow/end` fires exactly once per started run, after `result` is settled or as it settles. -- `dispose()` reaches quiescence within a bounded grace: it cancels, waits for the script to settle, and abandons a stuck script rather than hanging its caller (the engine documents what abandonment leaves behind). +- `dispose()` reaches quiescence within a bounded grace: it cancels, waits for the script to settle AND its started children to finish disposing, and abandons whatever is left rather than hanging its caller (the engine documents what abandonment leaves behind). ```ts cordis-catalog abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Source: [`packages/workflow/workflow/src/index.ts:188`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:191`](../../packages/workflow/workflow/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md index ebdf00869a..11f216f39e 100644 --- a/docs/core-data-structures/workflow.md +++ b/docs/core-data-structures/workflow.md @@ -47,7 +47,7 @@ interface WorkflowResult { ## A live run: `WorkflowRun` -The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — so the consumer maps a non-`completed` reason to an `isError` result. `dispose()` cancels, waits a bounded grace for the script to settle, then abandons it (the engine documents the abandonment semantics); it never hangs on a stuck script. +The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — so the consumer maps a non-`completed` reason to an `isError` result. `dispose()` cancels, waits a bounded grace for the script to settle AND its children to finish disposing, then abandons whatever is left (the engine documents the abandonment semantics); it never hangs on a stuck script. ```ts type-equiv interface WorkflowRun { @@ -65,4 +65,4 @@ Hook misuse inside a script — bad arguments, unknown/deferred `agent()` option ## Events -The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](../cordis-catalog/events.md)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — mirroring `subagent/start`/`subagent/end`. +The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](../cordis-catalog/events.md)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — and every listener receives its own payload clone, so mutating it corrupts neither the engine nor other listeners; the containment mirrors `subagent/start`/`subagent/end`. diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 372fce8f9a..35b65e3fb2 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -24,11 +24,11 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre ### The engine (dsh-workflow-vm): in-process node:vm -**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Scripts are model-written — the same trust level as the model's existing bash access — so genuine sandboxing is not the current requirement. The interface/implementation split exists precisely so a hardened engine can swap in later. Accepted, documented limitations: vm is not a security boundary, and the vm timeout covers only the initial synchronous slice — a pathological synchronous spin after the first await cannot be killed in-process; `dispose()` cancels, waits a bounded grace, then abandons. +**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Scripts are model-written — the same trust level as the model's existing bash access — so genuine sandboxing is not the current requirement. The interface/implementation split exists precisely so a hardened engine can swap in later. Accepted, documented limitations: vm is not a security boundary, and the vm timeout covers only the initial synchronous slice — a pathological synchronous spin after the first await cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. **Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. -**Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm (`args`, `agent()` results) are rebuilt INSIDE the realm via the context's own `JSON.parse`, so the script never holds a live host-prototype object. Realm functions (stages, thunks) are called, never materialized. +**Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, proxies included (the trap-free `util.types.isProxy`, checked before any inspection, so realm-side traps never run on the host stack), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm (`args`, `agent()` results) are rebuilt INSIDE the realm via the context's own `JSON.parse`, and `parallel`/`pipeline` resolve to realm-built arrays, so the script never holds a live host-prototype object. Realm functions (stages, thunks) are called, never materialized. **Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. @@ -38,7 +38,7 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai ### The foundation: structured output on the subagent seam -`agent({schema})` needs `SubagentStartRequest.outputSchema` to actually work; it was vocabulary without an implementation (`outputSchema: false` everywhere). Implemented in `dsh-subagent-inprocess` for both in-process backends: a globally registered `structured_output` capture tool whose per-child schema is enforced by a `prepend: true` `agent/request` listener doing FINAL-REQUEST enforcement (post-processing `await next()` — cooperative mutation would not survive a downstream listener returning a replacement request), an `agent/turn-continuation` veto after capture (no wasted extra model step), validation-retry in-turn via `ToolArgsError`, and a clean-finish nudge loop (`structuredNudgeRetries`). Lifetime is refcounted by backends (plugin lifetime) AND live runs (start → settle). The seam's `outputSchema` type became the raw JSON-Schema SUBSET (`StructuredOutputSchema` in dsh-tools: single-string `type`, `properties`/`required`/`additionalProperties`, `items`, scalar `enum`/`const`; anything unenforced is rejected loud) — the schema travels verbatim to the model as the forced tool's parameters, so the wire format, not the author DSL, is the right vocabulary. +`agent({schema})` needs `SubagentStartRequest.outputSchema` to actually work; it was vocabulary without an implementation (`outputSchema: false` everywhere). Implemented in `dsh-subagent-inprocess` for both in-process backends: a globally registered `structured_output` capture tool whose per-child schema is enforced by a `prepend: true` `agent/request` listener doing FINAL-REQUEST enforcement (post-processing `await next()` — cooperative mutation would not survive a downstream listener returning a replacement request), a `prepend: true` `agent/turn-continuation` veto after capture (no wasted extra model step, and an earlier-registered force-continue listener cannot short-circuit it), validation-retry in-turn via `ToolArgsError`, and a clean-finish nudge loop (`structuredNudgeRetries`). Lifetime is refcounted by backends (plugin lifetime) AND live runs (start → settle). The seam's `outputSchema` type became the raw JSON-Schema SUBSET (`StructuredOutputSchema` in dsh-tools: single-string `type`, `properties`/`required`/`additionalProperties`, `items`, scalar `enum`/`const`; anything unenforced is rejected loud) — the schema travels verbatim to the model as the forced tool's parameters, so the wire format, not the author DSL, is the right vocabulary. ## What was rejected diff --git a/packages/subagent/subagent-inprocess/README.md b/packages/subagent/subagent-inprocess/README.md index 1cbdccaee6..a257582464 100644 --- a/packages/subagent/subagent-inprocess/README.md +++ b/packages/subagent/subagent-inprocess/README.md @@ -24,7 +24,7 @@ Runs a child as a child [`Agent`](../../core/agent) on the same cordis context ( The mechanism behind `outputSchema` for in-process children. One globally registered `structured_output` capture tool (its registered parameters are a placeholder) plus two listeners, registered once per root context and shared by every holder: - an `agent/request` waterfall listener registered `prepend: true` that post-processes `await next()` — **final-request enforcement**: the request that hits the wire never carries `structured_output` for an agent without a structured run, and always carries the run's OWN schema (as the tool's `parameters`) for one that has it. Per-agent shaping lives here because the tool registry and prompt assembly are context-global while schemas differ per concurrent child; cooperative mutate-then-`next()` would not survive a downstream listener returning a replacement request. -- an `agent/turn-continuation` listener that stops a child's turn once its output is captured, so a successful capture doesn't buy a wasted extra model step. +- an `agent/turn-continuation` listener (also `prepend: true` — an earlier-registered force-continue listener returning without `next()` must not decide the turn before the veto runs) that stops a child's turn once its output is captured, so a successful capture doesn't buy a wasted extra model step. The capture tool validates each call against the run's schema (`validateStructuredValue`) — violations become an `INVALID_ARGS` isError result the model retries in-turn; a valid call records the value. diff --git a/packages/subagent/subagent-inprocess/src/structured.ts b/packages/subagent/subagent-inprocess/src/structured.ts index da371ac8f4..2a061ed56d 100644 --- a/packages/subagent/subagent-inprocess/src/structured.ts +++ b/packages/subagent/subagent-inprocess/src/structured.ts @@ -18,7 +18,9 @@ * * A companion `agent/turn-continuation` listener stops a child's turn once its * output is captured — without it, the loop's default "had tool calls ⇒ - * continue" buys a wasted extra model step per structured child. + * continue" buys a wasted extra model step per structured child. It is also + * `prepend: true`: the veto must run before any earlier-registered listener + * that could short-circuit the chain into a forced continue. * * Lifetime is refcounted with two kinds of holder: each backend acquires for * its plugin lifetime (so the tool exists before any run), and each structured @@ -183,11 +185,15 @@ function registerRuntime(root: Context, runtime: StructuredRuntime): void { // Stop a structured child's turn once its output is captured: the default // "had tool calls ⇒ continue" would otherwise buy a wasted extra model step - // after every successful capture. + // after every successful capture. `prepend: true` puts the veto OUTERMOST — + // an earlier-registered listener that short-circuits the chain (a goal-style + // force-continue returning without `next()`) would otherwise decide the turn + // before this listener ever ran, and no downstream decision may resurrect a + // structured turn that is already finished. runtime.disposers.push(root.on('agent/turn-continuation', function ( this: unknown, agent: Agent, _turn: number, _decision: ContinuationDecision, next: () => Promise, ): Promise { if (runtime.states.get(agent)?.captured) return Promise.resolve({ action: 'stop' }) return next() - })) + }, { prepend: true })) } diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts index 0a92c15fa8..cb046cc469 100644 --- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts @@ -5,6 +5,7 @@ import SessionStore from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import type { Agent, ContinuationDecision } from '@deepseek-ai/dsh-agent' import AgentLoop from '@deepseek-ai/dsh-agent-loop' import * as Invariants from '@deepseek-ai/dsh-invariants' import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent' @@ -85,6 +86,34 @@ describe('in-process structured output', () => { await run.dispose() }) + it('the captured-turn veto is prepend: an EARLIER force-continue listener cannot short-circuit it', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + // Registered BEFORE the structured runtime exists — without prepend, this + // goal-style listener would decide the turn first (returning WITHOUT + // calling next()) and the veto would never run. + ctx.on('agent/turn-continuation', () => Promise.resolve({ action: 'continue' })) + const acquisition = acquireStructuredRuntime(ctx) + const agent = { id: AgentId('structured-child') } as unknown as Agent + acquisition.attach(agent, SCHEMA) + const captured = await ctx.tools.execute({ + callId: 'call-1' as never, + name: STRUCTURED_OUTPUT_TOOL, + arguments: { answer: 1 }, + agent, + }) + expect(captured.isError).toBeFalsy() + const decision = await ctx.waterfall( + 'agent/turn-continuation', agent, 1, + { action: 'continue' }, + () => Promise.resolve({ action: 'continue' }), + ) + expect(decision).toEqual({ action: 'stop' }) + acquisition.detach(agent) + acquisition.release() + }) + it('an invalid call gets an INVALID_ARGS isError result and the model retries in-turn', async () => { const { ctx, parent } = await setup([ toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 'not-a-number' }), diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index 1cbc76c250..0ba1173f23 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -10,11 +10,11 @@ The first [`WorkflowService`](../workflow/README.md) implementation: an in-proce ## Realm discipline -Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a descriptor walk that never invokes accessors and rejects loud everything JSON cannot carry (accessors, exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values ENTERING the realm (`args`, `agent()` results) are rebuilt INSIDE the realm through the context's own `JSON.parse`, so the script never holds an object whose prototype chain reaches host intrinsics. +Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a descriptor walk that never invokes accessors and rejects loud everything JSON cannot carry (accessors, exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`, and proxies — rejected via the trap-free `util.types.isProxy` BEFORE any inspection could run a realm-side trap on the host stack), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values ENTERING the realm (`args`, `agent()` results) are rebuilt INSIDE the realm through the context's own `JSON.parse`, and the arrays `parallel`/`pipeline` resolve to are realm-built, so the script never holds an object whose prototype chain reaches host intrinsics. ## Limits, cancellation, disposal -Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`. Once a run settles, stray children a script fired without awaiting are aborted too. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). +Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). **Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin after the first await cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). @@ -27,4 +27,4 @@ Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap | `maxTotalAgents` | `1000` | Total `agent()` calls one run may start (runaway-loop backstop). | | `maxItemsPerCall` | `4096` | Items accepted by one `parallel()`/`pipeline()` call. | | `syncTimeoutMs` | `5000` | vm timeout for the initial synchronous slice and the meta evaluation. | -| `disposeGraceMs` | `5000` | How long `dispose()` waits for a cancelled script before abandoning it. | +| `disposeGraceMs` | `5000` | How long `dispose()` waits for a cancelled script and its children before abandoning them. | diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-vm/src/index.ts index 914ebb3ba6..4f6a506329 100644 --- a/packages/workflow/workflow-vm/src/index.ts +++ b/packages/workflow/workflow-vm/src/index.ts @@ -13,10 +13,12 @@ * is correctness containment, not a sandbox. * - The vm `timeout` covers only the initial SYNCHRONOUS slice of the script; * a pathological synchronous spin after the first await cannot be killed - * in-process. `dispose()` therefore waits a bounded grace and then ABANDONS - * a stuck script: its pending hook promises are already rejected and its - * settlement is contained (no unhandled rejection), but an abandoned - * synchronous spin would still occupy the event loop. + * in-process. `dispose()` waits a bounded grace for the script to settle + * AND its children (stray `agent()` calls included) to finish disposing, + * then ABANDONS whatever is left: pending hook promises are already + * rejected and the script's settlement is contained (no unhandled + * rejection), but an abandoned synchronous spin would still occupy the + * event loop. * * Plugin export shape: a default-exported {@link WorkflowService} subclass * (the class-based service form, like `dsh-bash-local`). @@ -142,12 +144,22 @@ export class VmWorkflowEngine extends WorkflowService { execution.cancel(reason) }, dispose: (): Promise => { - // Idempotent: cancel, then wait min(settle, grace). `result` never - // rejects, so the race needs no rejection handling; an unsettled - // script past the grace is abandoned per the module contract. + // Idempotent: cancel, then wait min(settle + child quiescence, grace). + // `result` and `quiesce()` never reject, so the race needs no + // rejection handling; a script or child still unsettled past the grace + // is abandoned per the module contract. disposed ??= (async () => { execution.cancel('workflow disposed') - await Promise.race([result, sleep(this.config.disposeGraceMs)]) + await Promise.race([ + (async () => { + await result + // The result settles with the SCRIPT; stray children a script + // fired without awaiting are still winding down — dispose must + // not return while they hold live resources. + await execution.quiesce() + })(), + sleep(this.config.disposeGraceMs), + ]) })() return disposed }, diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts index 70745cb4f6..3bf59f2a1f 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -10,7 +10,13 @@ * host containers, rejecting loud everything JSON cannot carry: * accessor properties, non-plain prototypes, functions, symbols (keys or * values), bigints, non-finite numbers, `undefined` values, cycles, sparse - * arrays, and arrays with non-index own properties. + * arrays, arrays with non-index own properties, and proxies. Proxies are + * rejected via the trap-free native `util.types.isProxy` check BEFORE any + * other inspection — a descriptor walk over a proxy would otherwise run its + * realm-side traps (`ownKeys`, `getOwnPropertyDescriptor`, `getPrototypeOf`) + * on the host stack, outside the vm's timed window, and a throwing trap would + * escape as a raw realm error instead of a {@link MaterializeError}. The same + * check guards the PROTOTYPE position (an object whose prototype is a proxy). * * Host objects are built with `Object.defineProperty` into a fresh `{}` — * never plain `target[key] =` assignment, which a `"__proto__"` key would turn @@ -24,6 +30,8 @@ * @module @deepseek-ai/dsh-workflow-vm/realm */ +import { types } from 'node:util' + /** Thrown by {@link materializeFromRealm}; the caller wraps it into the right `WorkflowError` code. */ export class MaterializeError extends Error { constructor(public readonly path: string, public readonly reason: string) { @@ -36,11 +44,13 @@ export class MaterializeError extends Error { * Whether an object's prototype chain is data-shaped: `null`, or a prototype * whose own prototype is `null` (the realm's `Object.prototype` — which we * cannot compare by identity across realms). A `Date`/`Map`/class instance - * has a longer chain and is rejected. + * has a longer chain and is rejected, as is a proxy sitting in the prototype + * position (checked trap-free BEFORE its own prototype is dereferenced). */ function hasPlainPrototype(value: object): boolean { const proto: unknown = Object.getPrototypeOf(value) if (proto === null) return true + if (types.isProxy(proto)) return false return Object.getPrototypeOf(proto) === null } @@ -81,6 +91,11 @@ function materialize(value: unknown, path: string, seen: Set): unknown { break } if (value === null) return null + // BEFORE anything else touches the object: every inspection below — + // Array.isArray aside — can trigger a proxy trap, running realm code on the + // host stack (module doc). isProxy is a native internal-slot check (no + // traps, catches revoked proxies, realm-agnostic). + if (types.isProxy(value)) throw new MaterializeError(path, 'proxies cannot cross the workflow realm boundary') const objectValue: object = value if (seen.has(objectValue)) throw new MaterializeError(path, 'circular references are not JSON data') seen.add(objectValue) diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index 04176a11ac..6c357408a8 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -9,8 +9,11 @@ * descriptor walks; values ENTERING the realm from the host (`args`, agent() * results) are rebuilt INSIDE the realm through the context's own * `JSON.parse`, so the script never holds an object whose prototype chain - * reaches host intrinsics. Realm functions (pipeline stages, parallel thunks) - * are called, not materialized — their values stay realm-side. + * reaches host intrinsics. The arrays `parallel`/`pipeline` resolve to are + * realm-built for the same reason (their ELEMENTS are realm values already — + * only the container needs rebuilding). Realm functions (pipeline stages, + * parallel thunks) are called, not materialized — their values stay + * realm-side. * * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments, * unsupported options/schemas, tripped caps, seam start failures, @@ -132,7 +135,10 @@ export class WorkflowExecution { private currentPhase: string | undefined private readonly context: vm.Context private readonly realmJsonParse: (text: string) => unknown + private readonly realmArrayFrom: (items: unknown[]) => unknown[] private readonly compiled: vm.Script + /** Every live `agent()` call promise — awaited or stray — for {@link quiesce}. */ + private readonly inFlightAgents = new Set>() constructor( private readonly ctx: Context, @@ -162,9 +168,12 @@ export class WorkflowExecution { // The realm's own JSON.parse — the host→realm rebuild channel. const realmJson = vm.runInContext('JSON', this.context) as { parse(text: string): unknown } this.realmJsonParse = (text: string) => realmJson.parse(text) + // The realm's own Array.from, bound NOW so a script reassigning its + // globals later cannot swap it: combinator results must be realm arrays. + this.realmArrayFrom = vm.runInContext('Array.from.bind(Array)', this.context) as (items: unknown[]) => unknown[] const globals: Record = { - agent: (prompt: unknown, opts?: unknown) => this.contain(this.agent(prompt, opts)), + agent: (prompt: unknown, opts?: unknown) => this.contain(this.track(this.agent(prompt, opts))), parallel: (thunks: unknown) => this.contain(this.parallel(thunks)), pipeline: (items: unknown, ...stages: unknown[]) => this.contain(this.pipeline(items, stages)), phase: (title: unknown) => { this.phase(title) }, @@ -216,8 +225,15 @@ export class WorkflowExecution { */ async drive(): Promise { try { + // Cancelled before the body ever ran (an already-aborted start signal): + // the script must not execute at all, let alone report `completed`. + if (this.isCancelled()) throw this.cancelledError() const scriptPromise = this.compiled.runInContext(this.context, { timeout: this.limits.syncTimeoutMs }) as Promise const raw: unknown = await this.contain(Promise.resolve(scriptPromise)) + // Cancelled while the body ran: a script that settled without touching + // another hook (or without any) must still report `cancelled` — the + // holder asked for cancellation and `completed` would be a lie. + if (this.isCancelled()) throw this.cancelledError() const value = raw === undefined ? null : this.materializeResult(raw) return { value, stopReason: 'completed', agentsStarted: this.started } } catch (error: unknown) { @@ -245,6 +261,31 @@ export class WorkflowExecution { return promise } + /** + * Register one `agent()` call promise for {@link quiesce} tracking; the + * entry drops when the call fully settles (which is AFTER its child's + * `dispose()` — the call wrapper disposes in its `finally`). + */ + private track(promise: Promise): Promise { + this.inFlightAgents.add(promise) + const drop = (): void => { this.inFlightAgents.delete(promise) } + promise.then(drop, drop) + return promise + } + + /** + * Settles once every `agent()` call — awaited or stray — has fully settled, + * INCLUDING each child's `dispose()`. The reap in {@link drive}'s finally + * aborts strays; this is the wait for those aborts to reach quiescence, so + * the engine's `dispose()` cannot return while a child is still winding + * down. Never rejects (the tracked promises' rejections are contained). + */ + async quiesce(): Promise { + while (this.inFlightAgents.size > 0) { + await Promise.allSettled([...this.inFlightAgents]) + } + } + private cancelledError(): WorkflowError { // cancel() arms cancelError before any caller can observe isCancelled() // === true; the fallback guards the type, not a reachable path. @@ -430,7 +471,7 @@ export class WorkflowExecution { } return thunk as () => unknown }) - return Promise.all(thunks.map(async (thunk) => { + const settled = await Promise.all(thunks.map(async (thunk) => { try { return await thunk() } catch (error: unknown) { @@ -438,6 +479,9 @@ export class WorkflowExecution { return null } })) + // The container must be a REALM array (module doc); the elements are + // realm values already. + return this.realmArrayFrom(settled) } /** The `pipeline(items, ...stages)` hook: per-item stage chains, NO cross-stage barrier. */ @@ -455,7 +499,7 @@ export class WorkflowExecution { } return stage as (previous: unknown, item: unknown, index: number) => unknown }) - return Promise.all(rawItems.map(async (item: unknown, index) => { + const settled = await Promise.all(rawItems.map(async (item: unknown, index) => { let value: unknown = item try { for (const stage of stages) { @@ -469,6 +513,9 @@ export class WorkflowExecution { return null } })) + // The container must be a REALM array (module doc); the elements are + // realm values already. + return this.realmArrayFrom(settled) } private assertItemCap(length: number, hook: string): void { diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-vm/tests/meta.spec.ts index 4768da49ff..27d18497d0 100644 --- a/packages/workflow/workflow-vm/tests/meta.spec.ts +++ b/packages/workflow/workflow-vm/tests/meta.spec.ts @@ -108,6 +108,14 @@ return 2` expect(error.message).toContain('JSON data') }) + it('rejects a meta literal containing a proxy as META_INVALID — its traps never run', () => { + // bad() rethrows anything that is not a WorkflowError, so a trap firing + // ('trap ran') would fail this test instead of mapping to META_INVALID. + const error = bad('export const meta = { name: "x", description: "d", phases: new Proxy([], { getPrototypeOf() { throw new Error("trap ran") } }) }') + expect(error.code).toBe('META_INVALID') + expect(error.message).toContain('proxies cannot cross') + }) + it('rejects shape violations with EVERY violation listed (META_INVALID)', () => { const error = bad('export const meta = { description: 7, bogus: 1 }\nreturn 1') expect(error.code).toBe('META_INVALID') diff --git a/packages/workflow/workflow-vm/tests/realm.spec.ts b/packages/workflow/workflow-vm/tests/realm.spec.ts index f374706dba..86deb49bd3 100644 --- a/packages/workflow/workflow-vm/tests/realm.spec.ts +++ b/packages/workflow/workflow-vm/tests/realm.spec.ts @@ -81,6 +81,27 @@ describe('materializeFromRealm', () => { expect(materializeFromRealm(inRealm('Object.assign(Object.create(null), { a: 1 })'))).toEqual({ a: 1 }) }) + it('rejects proxies (root, nested, revoked, host-realm) WITHOUT running any trap', () => { + const trapped = inRealm(`new Proxy({ a: 1 }, { + ownKeys() { throw new Error('trap ran') }, + getOwnPropertyDescriptor() { throw new Error('trap ran') }, + getPrototypeOf() { throw new Error('trap ran') }, + })`) + // A trap firing would surface 'trap ran' (a non-MaterializeError) instead. + expect(rejection(trapped)).toContain('proxies cannot cross') + expect(rejection(inRealm('{ nested: new Proxy([], {}) }'))).toContain('value.nested') + const revoked = inRealm('(() => { const r = Proxy.revocable({}, {}); r.revoke(); return r.proxy })()') + expect(rejection(revoked)).toContain('proxies cannot cross') + expect(rejection(new Proxy({}, {}))).toContain('proxies cannot cross') + }) + + it('rejects an object whose PROTOTYPE is a proxy without dereferencing through it', () => { + const value = inRealm(`Object.create(new Proxy({}, { + getPrototypeOf() { throw new Error('trap ran') }, + }))`) + expect(rejection(value)).toContain('exotic prototype') + }) + it('rejects cycles and accepts the same object reused as a sibling (a DAG)', () => { expect(rejection(inRealm('(() => { const o = {}; o.self = o; return o })()'))).toContain('circular') const dag = inRealm('(() => { const leaf = { v: 1 }; return { a: leaf, b: leaf } })()') diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index 9403dc912e..30dc0e4dfa 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -36,6 +36,7 @@ class StubProvider implements SubagentProvider { constructor( readonly name: string, private readonly reply?: (request: SubagentStartRequest, index: number) => SubagentResult, + private readonly disposeDelayMs = 0, ) {} start(request: SubagentStartRequest): SubagentRun { @@ -57,8 +58,17 @@ class StubProvider implements SubagentProvider { settle({ output: [], stopReason: 'aborted' }) }, dispose: () => { - controlled.disposed = true - return Promise.resolve() + if (this.disposeDelayMs === 0) { + controlled.disposed = true + return Promise.resolve() + } + // A slow-winding child (quiescence tests): disposal completes late. + return new Promise((resolve) => { + setTimeout(() => { + controlled.disposed = true + resolve() + }, this.disposeDelayMs) + }) }, } } @@ -73,12 +83,17 @@ interface SetupOptions { config?: Config reply?: (request: SubagentStartRequest, index: number) => SubagentResult manual?: boolean + disposeDelayMs?: number } async function setup(options?: SetupOptions) { const ctx = new Context() await ctx.plugin(SubagentService) - const provider = new StubProvider('stub', options?.manual ? undefined : options?.reply ?? (() => text('stub reply'))) + const provider = new StubProvider( + 'stub', + options?.manual ? undefined : options?.reply ?? (() => text('stub reply')), + options?.disposeDelayMs ?? 0, + ) ctx.subagents.registerProvider(provider) await ctx.plugin(VmWorkflowEngine, { provider: 'stub', ...options?.config }) return { ctx, provider, parent: fakeParent() } @@ -405,6 +420,50 @@ describe('dsh-workflow-vm', () => { expect((await run(ctx, parent, script('return typeof args'))).value).toBe('undefined') }) + it('parallel/pipeline resolve to REALM arrays: instanceof holds in-script, host intrinsics stay unreachable', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + const fromParallel = await parallel([() => agent('a'), () => 'plain']) + const fromPipeline = await pipeline([1], (prev) => prev + 1) + Object.getPrototypeOf(fromParallel).polluted = 'realm-only' + return { + parallelIsRealmArray: fromParallel instanceof Array, + pipelineIsRealmArray: fromPipeline instanceof Array, + values: [fromParallel[1], fromPipeline[0]], + } + `)) + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ + parallelIsRealmArray: true, + pipelineIsRealmArray: true, + values: ['plain', 2], + }) + // The script's prototype mutation stayed realm-side: the HOST + // Array.prototype was never reachable through a combinator result. + expect(([] as unknown as Record).polluted).toBeUndefined() + }) + + it('a returned proxy is rejected as RESULT_UNSERIALIZABLE without running its traps', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + return new Proxy({ a: 1 }, { ownKeys() { throw new Error('trap ran') } }) + `)) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('not plain JSON data') + expect(result.error).toContain('proxies cannot cross') + expect(result.error).not.toContain('trap ran') + }) + + it('agent() options passed as a proxy are rejected loudly, traps never invoked', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + return await agent('p', new Proxy({}, { ownKeys() { throw new Error('trap ran') } })) + `)) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('options must be plain JSON data') + expect(result.error).not.toContain('trap ran') + }) + it('a non-JSON return value fails loud as RESULT_UNSERIALIZABLE', async () => { const { ctx, parent } = await setup() const withDate = await run(ctx, parent, script('return { when: new Date(0) }')) @@ -452,6 +511,51 @@ describe('dsh-workflow-vm', () => { await handle.dispose() }) + it('an already-aborted signal cancels a HOOK-FREE script: the body never runs at all', async () => { + const { ctx, parent } = await setup() + const controller = new AbortController() + controller.abort() + const logs: string[] = [] + ctx.on('workflow/log', (_info, message) => { logs.push(message) }) + const handle = ctx.workflows.start({ script: script("log('ran')\nreturn 123"), parent, signal: controller.signal }) + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(result.value).toBeNull() + expect(logs).toEqual([]) + await handle.dispose() + }) + + it('cancel() right after start() reports cancelled even when the script needed no hooks', async () => { + const { ctx, parent } = await setup() + const handle = ctx.workflows.start({ script: script('return 123'), parent }) + handle.cancel('changed my mind') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(result.value).toBeNull() + expect(result.error).toContain('changed my mind') + await handle.dispose() + }) + + it('an agent() call AFTER a mid-run cancel rejects at entry — no child ever starts', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + script: script(` + await agent('first') + return await agent('second') + `), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + // Same synchronous block: the first child settles completed, then the + // cancel lands BEFORE the script's continuation can call agent() again. + provider.runs[0]!.settle(text('first done')) + handle.cancel('mid-run') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(provider.runs.length).toBe(1) + await handle.dispose() + }) + it('the signal aborting mid-run cancels like cancel()', async () => { const { ctx, parent, provider } = await setup({ manual: true }) const controller = new AbortController() @@ -577,6 +681,24 @@ describe('dsh-workflow-vm', () => { }) await handle.dispose() }) + + it('dispose() waits for a stray child to FINISH disposing (quiescence), not just the script settle', async () => { + const { ctx, parent, provider } = await setup({ manual: true, disposeDelayMs: 40 }) + const handle = ctx.workflows.start({ + script: script(` + agent('stray') + return 'done without awaiting' + `), + parent, + }) + const result = await handle.result + expect(result.stopReason).toBe('completed') + expect(provider.runs.length).toBe(1) + await handle.dispose() + // Not a waitFor: by the time dispose() returns, the slow child disposal + // must already be complete. + expect(provider.runs[0]!.disposed).toBe(true) + }) }) describe('service surface', () => { @@ -595,6 +717,24 @@ describe('dsh-workflow-vm', () => { await second.dispose() }) + it('a listener mutating one event payload cannot corrupt later events (per-emission snapshots)', async () => { + const { ctx, parent } = await setup() + const ends: unknown[] = [] + let endInfo: WorkflowRunInfo | undefined + ctx.on('workflow/agent-start', (info, agent) => { + agent.seq = 999 + agent.label = 'HACKED' + info.meta.name = 'HACKED' + }) + ctx.on('workflow/agent-end', (info, agent) => { + ends.push(agent) + endInfo = info + }) + await run(ctx, parent, script("return await agent('job', { label: 'honest' })")) + expect(ends[0]).toMatchObject({ seq: 1, label: 'honest', outcome: 'completed' }) + expect(endInfo!.meta.name).toBe('test-flow') + }) + it('unregisters ctx.workflows when the engine fiber is disposed (HMR safety)', async () => { const ctx = new Context() await ctx.plugin(SubagentService) diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md index 1dece68d38..46efa2f2d0 100644 --- a/packages/workflow/workflow/README.md +++ b/packages/workflow/workflow/README.md @@ -4,9 +4,9 @@ The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a wor ## Service: `WorkflowService` (abstract) -`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). `dispose()` must reach quiescence within a bounded grace (cancel → wait → abandon), never hanging its caller. +`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. -The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment (a throwing subscriber is logged, never propagated, and cannot starve later listeners) — the same guarantee as the subagent seam's lifecycle emits. +The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits. ## Vocabulary diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index ab5e056b37..5f340e2f93 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -13,8 +13,10 @@ * carry {@link WorkflowRunInfo} (id + meta), never the live {@link WorkflowRun} * — a listener must not gain `cancel`/`dispose`; control stays with the * `start()` caller holding the run. Every emit is per-listener contained (a - * throwing subscriber is logged, never propagated), so one bad observer can - * neither strand a live run nor starve later listeners. + * throwing subscriber is logged, never propagated) and every listener gets its + * own payload clone (mutating it corrupts nothing), so one bad observer can + * neither strand a live run, starve later listeners, nor poison another + * listener's view. * * @module @deepseek-ai/dsh-workflow */ @@ -182,8 +184,9 @@ export function isFatalWorkflowError(error: unknown): boolean { * snapshots, per-listener containment); `workflow/end` fires exactly once * per started run, after `result` is settled or as it settles. * - `dispose()` reaches quiescence within a bounded grace: it cancels, waits - * for the script to settle, and abandons a stuck script rather than - * hanging its caller (the engine documents what abandonment leaves behind). + * for the script to settle AND its started children to finish disposing, + * and abandons whatever is left rather than hanging its caller (the engine + * documents what abandonment leaves behind). */ export abstract class WorkflowService extends Service { constructor(ctx: Context) { @@ -199,12 +202,16 @@ export abstract class WorkflowService extends Service { abstract start(request: WorkflowStartRequest): WorkflowRun /** - * Emit one `workflow/*` lifecycle event with PER-LISTENER containment: - * dispatch each subscriber individually and log (never propagate) a thrown - * one, so one bad subscriber can neither fail the engine mid-run, surface as - * an unhandled rejection on a detached settle hook, nor starve the listeners - * registered after it (cordis `emit` halts on the first throw — same - * guarantee as the subagent seam's lifecycle emits). + * Emit one `workflow/*` lifecycle event with PER-LISTENER containment and + * PER-LISTENER payload snapshots: each subscriber is dispatched individually + * with its OWN structural clone of the payload (the payloads are plain JSON + * data by the seam contract), so a listener mutating what it received can + * corrupt neither the engine's live state nor any other listener's or later + * event's view; a thrown listener is logged (never propagated), so one bad + * subscriber can neither fail the engine mid-run, surface as an unhandled + * rejection on a detached settle hook, nor starve the listeners registered + * after it (cordis `emit` halts on the first throw — same guarantee as the + * subagent seam's lifecycle emits). * @param name - the `workflow/*` event to dispatch. * @param args - the event's payload, matching its declared signature. */ @@ -213,7 +220,7 @@ export abstract class WorkflowService extends Service { try { // The declared workflow/* signatures are all void-returning emits; the // dispatch callback applies the payload tuple. - ;(callback as (...payload: unknown[]) => void)(...args) + ;(callback as (...payload: unknown[]) => void)(...structuredClone(args)) } catch (error: unknown) { this.ctx.logger.warn(`workflow: ${name} listener threw: ${String(error)}`) } diff --git a/packages/workflow/workflow/tests/workflow.spec.ts b/packages/workflow/workflow/tests/workflow.spec.ts index a5bd8cd1ed..b303c02962 100644 --- a/packages/workflow/workflow/tests/workflow.spec.ts +++ b/packages/workflow/workflow/tests/workflow.spec.ts @@ -66,6 +66,28 @@ describe('dsh-workflow (interface)', () => { ]) }) + it('gives each listener its OWN payload snapshot: mutation corrupts neither peers nor the caller', async () => { + const ctx = new Context() + await ctx.plugin(StubEngine) + const seen: string[] = [] + ctx.on('workflow/agent-start', (info, agent) => { + agent.label = 'HACKED' + info.meta.name = 'HACKED' + seen.push('mutator') + }) + ctx.on('workflow/agent-start', (info, agent) => { + seen.push(`${info.meta.name}/${agent.label}`) + }) + const engine = ctx.workflows as StubEngine + const info: WorkflowRunInfo = { id: WorkflowRunId('run-2'), meta: { name: 'w', description: 'd' } } + const payload = { seq: 1, label: 'original', childId: 'c' } + engine.emit('workflow/agent-start', info, payload) + expect(seen).toEqual(['mutator', 'w/original']) + // The caller's own objects are pristine too — no listener ever saw them. + expect(info.meta.name).toBe('w') + expect(payload.label).toBe('original') + }) + it('contains a throwing listener PER LISTENER: later listeners still run, nothing propagates', async () => { const ctx = new Context() await ctx.plugin(StubEngine) From 57b9910339658b17c86eea0eb8aa2b3406fb563b Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 19:39:19 +0800 Subject: [PATCH 007/119] workflow: total, contained rendering of hostile thrown script values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex code-review round 2: errorText() read .stack/.message as plain property gets and fell back to String(error) — a script throwing a value with a throwing accessor (or toString/Symbol.toPrimitive) ran realm code in drive()'s catch and made WorkflowRun.result REJECT, which the detached workflow/end hook turned into an unhandledRejection (process death under dsh-app-boot). Replaced with describeThrown in dsh-workflow-vm/realm: total (never throws), proxy-labelling before any inspection, own-descriptor reads, String() only on primitives, and a CONTAINED stack-getter invocation — modern V8 (Node >= 22) makes stack an own ACCESSOR on genuine Errors, so refusing all accessors would lose every real stack and the lineOffset line numbers; a hostile getter's throw is swallowed and rendering falls back to message. The meta-literal eval catch had the same String(error) exposure and now uses the same renderer. Regression tests: a hostile-thrown-values table through the real engine (throwing stack/message getters, data stack, setter-only stack, proxy, Symbol.toPrimitive, function, null) asserting result resolves 'error' with the expected rendering and NO unhandledRejection fires; a meta-path hostile throw mapping to META_INVALID. --- .../feature/2026-07-05-dynamic-workflows.md | 2 +- packages/workflow/workflow-vm/README.md | 2 +- packages/workflow/workflow-vm/src/meta.ts | 7 +- packages/workflow/workflow-vm/src/realm.ts | 72 +++++++++++++++++++ packages/workflow/workflow-vm/src/runtime.ts | 22 ++---- .../workflow/workflow-vm/tests/meta.spec.ts | 7 ++ .../workflow-vm/tests/workflow-vm.spec.ts | 33 +++++++++ 7 files changed, 124 insertions(+), 21 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 35b65e3fb2..c1fbbe7427 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -30,7 +30,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre **Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, proxies included (the trap-free `util.types.isProxy`, checked before any inspection, so realm-side traps never run on the host stack), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm (`args`, `agent()` results) are rebuilt INSIDE the realm via the context's own `JSON.parse`, and `parallel`/`pipeline` resolve to realm-built arrays, so the script never holds a live host-prototype object. Realm functions (stages, thunks) are called, never materialized. -**Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. +**Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Thrown script values (and meta-evaluation throws) are rendered by the total `describeThrown` — fixed labels for proxies/functions, own-descriptor reads, `String()` only on primitives, and a CONTAINED stack-getter call (modern V8 makes `stack` an own accessor on real Errors; a hostile getter's throw is swallowed) — so a hostile thrown value can neither escape the catch path raw nor make `result` reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. ### The consumer (dsh-tool-workflow) diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index 0ba1173f23..1efe4eb5af 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -14,7 +14,7 @@ Values ENTERING the host (the meta literal, hook options/schemas, the script's r ## Limits, cancellation, disposal -Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). +Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those), and thrown script values are rendered by the total `describeThrown` (proxy-labelling, own-descriptor reads, a contained stack-getter call), so a hostile throw (`{ get stack() { throw ... } }`) cannot make `result` reject. **Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin after the first await cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). diff --git a/packages/workflow/workflow-vm/src/meta.ts b/packages/workflow/workflow-vm/src/meta.ts index bb97ad7d39..edf95eb22c 100644 --- a/packages/workflow/workflow-vm/src/meta.ts +++ b/packages/workflow/workflow-vm/src/meta.ts @@ -20,7 +20,7 @@ import * as vm from 'node:vm' import { WorkflowError } from '@deepseek-ai/dsh-workflow' import type { WorkflowMeta, WorkflowPhase } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError } from './realm.ts' +import { materializeFromRealm, MaterializeError, describeThrown } from './realm.ts' /** The result of {@link extractMeta}: the validated meta and the runnable body. */ export interface ExtractedScript { @@ -174,7 +174,10 @@ export function extractMeta(script: string, evalTimeoutMs: number): ExtractedScr // below are part of the same boundary. evaluated = vm.runInNewContext(`(${literal})`, undefined, { timeout: evalTimeoutMs }) } catch (error: unknown) { - throw new WorkflowError(`meta block failed to evaluate as a pure literal: ${String(error)}`, 'META_INVALID', { cause: error }) + // describeThrown, not String(): an expression in the literal can THROW a + // hostile value (a throwing toString/accessor), and this catch must map + // it to META_INVALID rather than let realm code run or a raw error escape. + throw new WorkflowError(`meta block failed to evaluate as a pure literal: ${describeThrown(error)}`, 'META_INVALID', { cause: error }) } let data: unknown try { diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts index 3bf59f2a1f..b1389a999c 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -27,6 +27,11 @@ * chain, so the engine rebuilds inbound values INSIDE the realm via the * context's own `JSON.parse` (see the runtime). * + * {@link describeThrown} is the same discipline for the one place realm + * values reach the host WITHOUT materialization: rendering a thrown value + * for a failure report. It never throws; the only realm code it can invoke + * is a stack getter, contained (see its doc). + * * @module @deepseek-ai/dsh-workflow-vm/realm */ @@ -40,6 +45,73 @@ export class MaterializeError extends Error { } } +/** + * Render a value THROWN by realm code (a script failure, a meta-literal + * evaluation failure) as text, without ever throwing itself — the callers sit + * in catch blocks whose totality is a seam contract (`WorkflowRun.result` + * never rejects). Plain property reads and `String(value)` are hostile-value + * hazards (`{ get stack() { throw ... } }`, a throwing + * `toString`/`Symbol.toPrimitive`), so: proxies render as a fixed label + * (trap-free `isProxy`, before any inspection); `message` is read as an OWN + * DATA descriptor only; everything else object-shaped renders as + * `[object Object]` without being touched; only primitives (which cannot + * carry code) reach `String()`. The one exception is the `stack` getter — + * modern V8 makes `stack` an own ACCESSOR on genuine `Error`s, so it is + * invoked (that is how real stacks, with the script's own line numbers via + * the compile lineOffset, are obtained) but CONTAINED: a hostile getter's + * throw is swallowed and rendering falls back to message. Detection is + * structural, not `instanceof` — a realm Error is not an instance of the host + * class. + * @param error - the thrown value, of any shape and any realm. + * @returns human-readable text for the failure report; prefers the stack. + */ +export function describeThrown(error: unknown): string { + switch (typeof error) { + case 'object': + break + case 'function': + return '[thrown function]' + default: + // Primitives (string/number/boolean/bigint/symbol/undefined): String() + // cannot reach user code on these. + return String(error) + } + if (error === null) return 'null' + if (types.isProxy(error)) return '[thrown proxy]' + const stack = readStack(error) + if (typeof stack === 'string' && stack.length > 0) return stack + const message = ownDataProperty(error, 'message') + if (typeof message === 'string') return message + return '[object Object]' +} + +/** + * Read `error.stack`, tolerating both descriptor shapes: an own DATA property + * (older V8, plain objects) and the modern own ACCESSOR pair (the Error Stack + * Accessor proposal). Invoking the getter is the only way to obtain a real + * stack; on a hostile object that getter is user code, so the call is + * contained — a throw yields `undefined` (the caller falls back to message), + * and a synchronous spin is the engine's already-accepted post-await + * limitation (a script can spin directly just the same). + */ +function readStack(error: object): unknown { + const descriptor = Object.getOwnPropertyDescriptor(error, 'stack') + if (descriptor === undefined) return undefined + if ('value' in descriptor) return descriptor.value + if (typeof descriptor.get !== 'function') return undefined + try { + return descriptor.get.call(error) + } catch { + return undefined // a hostile stack getter threw; message/fallback renders instead + } +} + +/** An own DATA property's value (`undefined` for absent or accessor); never invokes user code on a non-proxy object. */ +function ownDataProperty(value: object, key: string): unknown { + const descriptor = Object.getOwnPropertyDescriptor(value, key) + return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined +} + /** * Whether an object's prototype chain is data-shaped: `null`, or a prototype * whose own prototype is `null` (the realm's `Object.prototype` — which we diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index 6c357408a8..c108d2cf69 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -41,7 +41,7 @@ import type { WorkflowMeta, WorkflowResult, } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError } from './realm.ts' +import { materializeFromRealm, MaterializeError, describeThrown } from './realm.ts' /** The per-run knobs the engine resolves from its Config. */ export interface ExecutionLimits { @@ -97,21 +97,6 @@ function outputText(blocks: ContentBlock[]): string { .join('') } -/** - * Render a script failure for the result: prefer the stack (it carries the - * script's own line numbers via the compile lineOffset), then the message. - * STRUCTURAL detection, not `instanceof Error` — a realm-thrown Error is not - * an instance of the host Error class. - */ -function errorText(error: unknown): string { - if (typeof error === 'object' && error !== null) { - const maybe = error as { stack?: unknown; message?: unknown } - if (typeof maybe.stack === 'string' && maybe.stack.length > 0) return maybe.stack - if (typeof maybe.message === 'string') return maybe.message - } - return String(error) -} - /** A short display label derived from the prompt when the script passes none. */ function defaultLabel(prompt: string): string { const newline = prompt.indexOf('\n') @@ -240,7 +225,10 @@ export class WorkflowExecution { if (error instanceof WorkflowError && error.code === 'CANCELLED') { return { value: null, stopReason: 'cancelled', error: error.message, agentsStarted: this.started } } - return { value: null, stopReason: 'error', error: errorText(error), agentsStarted: this.started } + // describeThrown is total and trap-free: a hostile thrown value (a + // throwing accessor, a proxy) cannot make this catch throw — drive() + // resolving is the `result` never-rejects seam contract. + return { value: null, stopReason: 'error', error: describeThrown(error), agentsStarted: this.started } } finally { // Reap strays: a script that fired agent() calls without awaiting them // leaves live children behind after settlement — abort them all. (The diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-vm/tests/meta.spec.ts index 27d18497d0..7b5a929046 100644 --- a/packages/workflow/workflow-vm/tests/meta.spec.ts +++ b/packages/workflow/workflow-vm/tests/meta.spec.ts @@ -116,6 +116,13 @@ return 2` expect(error.message).toContain('proxies cannot cross') }) + it('a meta expression THROWING a hostile value maps to META_INVALID — rendering runs no realm code', () => { + const error = bad('export const meta = { name: (() => { throw { get stack() { throw new Error("boom") }, toString() { throw new Error("boom") } } })(), description: "d" }\nreturn 1') + expect(error.code).toBe('META_INVALID') + expect(error.message).toContain('pure literal') + expect(error.message).toContain('[object Object]') + }) + it('rejects shape violations with EVERY violation listed (META_INVALID)', () => { const error = bad('export const meta = { description: 7, bogus: 1 }\nreturn 1') expect(error.code).toBe('META_INVALID') diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index 30dc0e4dfa..e0518c8192 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -589,6 +589,39 @@ describe('dsh-workflow-vm', () => { expect(result.error).toBe('[object Object]') }) + it('hostile thrown values render contained: result NEVER rejects, no unhandled rejection', async () => { + const unhandled: unknown[] = [] + const onUnhandled = (reason: unknown): void => { unhandled.push(reason) } + process.on('unhandledRejection', onUnhandled) + try { + const { ctx, parent } = await setup() + // Each thrown value would run realm code (or throw) under a plain + // property read or String(); rendering must stay total — the only + // permitted realm call is the CONTAINED stack getter. + const cases: [string, string][] = [ + ["throw { get stack() { throw new Error('stack getter threw') } }", '[object Object]'], + ["throw { get stack() { throw new Error('x') }, message: 'getter threw, message renders' }", 'getter threw, message renders'], + ["throw { get message() { throw new Error('message getter ran') } }", '[object Object]'], + ["throw { stack: 'custom data stack' }", 'custom data stack'], + ["throw (() => { const o = { message: 'setter-only stack' }; Object.defineProperty(o, 'stack', { set() {} }); return o })()", 'setter-only stack'], + ["throw new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('trap ran') } })", '[thrown proxy]'], + ["throw { [Symbol.toPrimitive]() { throw new Error('toPrimitive ran') } }", '[object Object]'], + ['throw () => 1', '[thrown function]'], + ['throw null', 'null'], + ] + for (const [body, rendered] of cases) { + const result = await run(ctx, parent, script(body)) + expect(result.stopReason).toBe('error') + expect(result.error).toBe(rendered) + } + // Let any stray rejection reach the process hook before asserting. + await new Promise(resolve => setTimeout(resolve, 20)) + expect(unhandled).toEqual([]) + } finally { + process.off('unhandledRejection', onUnhandled) + } + }) + it('falls back to the message for an Error whose stack was stripped', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` From fff2e1f33ddf97e45fd868885d990f604476dbe4 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 20:32:35 +0800 Subject: [PATCH 008/119] workflow: render thrown script values inside the realm's execution window MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex code-review round 3: the round-2 'contained stack getter' still let a script escape the vm sync-slice timeout — throw { get stack() { while(true){} } } put the spin on the HOST catch path, where no timeout applies (verified: a direct sync-slice spin dies by the timeout; the getter-hidden one hung the process). Identity-trusting the native getter is also insufficient: V8 stack formatting reads script-controllable hooks at format time (Error.prepareStackTrace, a subclass name getter — both empirically confirmed), so ANY host-side formatting of a realm error can run realm code. The fix moves rendering into the realm itself: the compiled body (and the meta literal) is wrapped in a realm-side catch that pre-renders the thrown value to a string (REALM_THROWN_RENDERER_SOURCE) — a hostile accessor/toString now runs as ordinary script code, killed by the sync-slice timeout or falling under the documented post-await spin limitation; host WorkflowErrors pass through for the CANCELLED mapping. The host catch descriptor-reads the pre-rendered string (thrownRendering) or falls back to describeThrown, which invokes no getter whose identity is not the host realm's own native stack getter. Tests: hostile-table expectations updated for realm-side rendering; new regressions for the getter-hidden sync spin dying by the vm timeout (engine + meta paths) and for a hostile thenable rejection that bypasses the realm wrapper (renders host-side, proxy labelled, traps never run); describeThrown/ thrownRendering unit tables including the realm-error identity-mismatch case. --- .../feature/2026-07-05-dynamic-workflows.md | 2 +- packages/workflow/workflow-vm/README.md | 2 +- packages/workflow/workflow-vm/src/meta.ts | 22 ++-- packages/workflow/workflow-vm/src/realm.ts | 108 ++++++++++++------ packages/workflow/workflow-vm/src/runtime.ts | 27 +++-- .../workflow/workflow-vm/tests/meta.spec.ts | 17 ++- .../workflow/workflow-vm/tests/realm.spec.ts | 45 +++++++- .../workflow-vm/tests/workflow-vm.spec.ts | 37 ++++-- 8 files changed, 199 insertions(+), 61 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index c1fbbe7427..6f8678ecea 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -30,7 +30,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre **Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, proxies included (the trap-free `util.types.isProxy`, checked before any inspection, so realm-side traps never run on the host stack), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm (`args`, `agent()` results) are rebuilt INSIDE the realm via the context's own `JSON.parse`, and `parallel`/`pipeline` resolve to realm-built arrays, so the script never holds a live host-prototype object. Realm functions (stages, thunks) are called, never materialized. -**Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Thrown script values (and meta-evaluation throws) are rendered by the total `describeThrown` — fixed labels for proxies/functions, own-descriptor reads, `String()` only on primitives, and a CONTAINED stack-getter call (modern V8 makes `stack` an own accessor on real Errors; a hostile getter's throw is swallowed) — so a hostile thrown value can neither escape the catch path raw nor make `result` reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. +**Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Thrown script/meta values are pre-rendered to a string by a realm-side catch compiled into the wrapper (rendering runs inside the realm's own execution window, so a hostile `stack` getter dies by the vm sync-slice timeout like any other script code — host-side formatting of realm errors is unfixable in general, since V8 stack formatting invokes script-controllable `name`/`prepareStackTrace` hooks); the host catch descriptor-reads that string or falls back to `describeThrown` (fixed labels, own-data reads, an identity-verified host-native stack getter), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. ### The consumer (dsh-tool-workflow) diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index 1efe4eb5af..e519ce7c0e 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -14,7 +14,7 @@ Values ENTERING the host (the meta literal, hook options/schemas, the script's r ## Limits, cancellation, disposal -Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those), and thrown script values are rendered by the total `describeThrown` (proxy-labelling, own-descriptor reads, a contained stack-getter call), so a hostile throw (`{ get stack() { throw ... } }`) cannot make `result` reject. +Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). Thrown script values are pre-rendered to a string INSIDE the realm's execution window (the body is compiled into a realm-side catch), so a hostile `stack` getter is subject to the vm sync-slice timeout like any other script code; the host catch only descriptor-reads that string, falling back to `describeThrown` (fixed labels, own-data reads, an identity-verified host-native stack getter) — `result` cannot reject. **Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin after the first await cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). diff --git a/packages/workflow/workflow-vm/src/meta.ts b/packages/workflow/workflow-vm/src/meta.ts index edf95eb22c..bcb891e85e 100644 --- a/packages/workflow/workflow-vm/src/meta.ts +++ b/packages/workflow/workflow-vm/src/meta.ts @@ -20,7 +20,7 @@ import * as vm from 'node:vm' import { WorkflowError } from '@deepseek-ai/dsh-workflow' import type { WorkflowMeta, WorkflowPhase } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError, describeThrown } from './realm.ts' +import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering, REALM_THROWN_RENDERER_SOURCE } from './realm.ts' /** The result of {@link extractMeta}: the validated meta and the runnable body. */ export interface ExtractedScript { @@ -171,13 +171,21 @@ export function extractMeta(script: string, evalTimeoutMs: number): ExtractedScr // An EMPTY context: any non-literal reference (a variable, a call) throws // here. The result — data only — is what the contract checks; a getter or // IIFE can still run, which is why the timeout and the materialization - // below are part of the same boundary. - evaluated = vm.runInNewContext(`(${literal})`, undefined, { timeout: evalTimeoutMs }) + // below are part of the same boundary. A thrown value is pre-rendered by + // the realm-side catch INSIDE the timed window, so a hostile + // stack/message/toString can neither run on the host catch path nor + // outlive the timeout. + evaluated = vm.runInNewContext( + `(() => { try { return (${literal}) } catch (e) { throw (${REALM_THROWN_RENDERER_SOURCE})(e) } })()`, + undefined, + { timeout: evalTimeoutMs }, + ) } catch (error: unknown) { - // describeThrown, not String(): an expression in the literal can THROW a - // hostile value (a throwing toString/accessor), and this catch must map - // it to META_INVALID rather than let realm code run or a raw error escape. - throw new WorkflowError(`meta block failed to evaluate as a pure literal: ${describeThrown(error)}`, 'META_INVALID', { cause: error }) + throw new WorkflowError( + `meta block failed to evaluate as a pure literal: ${thrownRendering(error) ?? describeThrown(error)}`, + 'META_INVALID', + { cause: error }, + ) } let data: unknown try { diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts index b1389a999c..fca93caac4 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -27,10 +27,16 @@ * chain, so the engine rebuilds inbound values INSIDE the realm via the * context's own `JSON.parse` (see the runtime). * - * {@link describeThrown} is the same discipline for the one place realm - * values reach the host WITHOUT materialization: rendering a thrown value - * for a failure report. It never throws; the only realm code it can invoke - * is a stack getter, contained (see its doc). + * {@link REALM_THROWN_RENDERER_SOURCE}, {@link thrownRendering}, and + * {@link describeThrown} are the same discipline for the one place realm + * values reach the host WITHOUT materialization: a thrown value crossing into + * a host catch block. The renderer runs INSIDE the realm's own execution + * window (compiled into the script wrapper), so reading a hostile + * accessor/`toString` there is subject to the vm sync-slice timeout exactly + * like any other script code; the host side only descriptor-reads the + * pre-rendered string, or falls back to {@link describeThrown}, which invokes + * no getter whose function identity is not the host realm's own native stack + * getter. * * @module @deepseek-ai/dsh-workflow-vm/realm */ @@ -46,22 +52,66 @@ export class MaterializeError extends Error { } /** - * Render a value THROWN by realm code (a script failure, a meta-literal - * evaluation failure) as text, without ever throwing itself — the callers sit - * in catch blocks whose totality is a seam contract (`WorkflowRun.result` - * never rejects). Plain property reads and `String(value)` are hostile-value - * hazards (`{ get stack() { throw ... } }`, a throwing - * `toString`/`Symbol.toPrimitive`), so: proxies render as a fixed label - * (trap-free `isProxy`, before any inspection); `message` is read as an OWN - * DATA descriptor only; everything else object-shaped renders as - * `[object Object]` without being touched; only primitives (which cannot - * carry code) reach `String()`. The one exception is the `stack` getter — - * modern V8 makes `stack` an own ACCESSOR on genuine `Error`s, so it is - * invoked (that is how real stacks, with the script's own line numbers via - * the compile lineOffset, are obtained) but CONTAINED: a hostile getter's - * throw is swallowed and rendering falls back to message. Detection is - * structural, not `instanceof` — a realm Error is not an instance of the host - * class. + * Realm-SOURCE text (an arrow-function expression) the engine compiles into + * its script wrappers: `throw (RENDERER)(e)` inside a catch around the whole + * body/literal. It renders the thrown value to a string INSIDE the realm's + * own execution window — a hostile `stack`/`message` accessor or `toString` + * invoked here is subject to the vm sync-slice timeout like any other script + * code (and post-await it is the engine's accepted spin limitation, identical + * to a script reading `e.stack` in its own catch). Host `WorkflowError`s + * thrown by hooks pass through unwrapped (duck-checked by name — a realm + * forgery fails the host's `instanceof` and merely renders data-only); + * everything else becomes `{ __wfThrown: }`, whose only consumer is + * {@link thrownRendering}. Every read is individually contained, so the + * renderer itself never throws. + */ +export const REALM_THROWN_RENDERER_SOURCE = `(e) => { + try { if (e && e.name === 'WorkflowError') return e } catch { /* hostile name getter: fall through to rendering */ } + const rendered = (() => { + try { if (e && typeof e.stack === 'string' && e.stack.length > 0) return e.stack } catch { /* hostile stack getter */ } + try { if (e && typeof e.message === 'string') return e.message } catch { /* hostile message getter */ } + try { return String(e) } catch { /* hostile toString/Symbol.toPrimitive */ } + return '[unrenderable thrown value]' + })() + return { __wfThrown: rendered } +}` + +/** + * The pre-rendered failure text carried by a realm-catch wrapper object + * (`{ __wfThrown: string }` from {@link REALM_THROWN_RENDERER_SOURCE}), or + * `undefined` when `error` is not such a wrapper. Descriptor-read and + * proxy-guarded: never invokes user code. + * @param error - the value a host catch received from script execution. + * @returns the realm-rendered string, or `undefined` to fall back to + * {@link describeThrown}. + */ +export function thrownRendering(error: unknown): string | undefined { + if (typeof error !== 'object' || error === null || types.isProxy(error)) return undefined + const value = ownDataProperty(error, '__wfThrown') + return typeof value === 'string' ? value : undefined +} + +/** + * The host realm's own native `stack` getter (modern V8 makes `stack` an own + * ACCESSOR on Errors); `undefined` where it is a data property. Typed through + * a structural view of the descriptor — it is only ever identity-compared or + * `.call`ed on an explicit receiver, never invoked unbound. + */ +const HOST_STACK_GETTER: unknown = (Object.getOwnPropertyDescriptor(new Error(), 'stack') as { get?: unknown } | undefined)?.get + +/** + * Render a thrown value HOST-SIDE without ever throwing and without running + * any code the host does not own: proxies become a fixed label (trap-free + * `isProxy` before any inspection); `stack` is read as an own data descriptor, + * or through its getter ONLY when that getter's function identity is the host + * realm's own native stack getter (an unforgeable check — realm code cannot + * hold that identity, and the host realm's `prepareStackTrace` is the host's + * own trust domain); `message` is an own-data read; anything else + * object-shaped renders as `[object Object]` untouched; only primitives + * (which cannot carry code) reach `String()`. Used for host-thrown errors + * (vm timeouts, `WorkflowError`s) and as the fallback for adversarial values + * that bypassed the realm-side renderer (e.g. a hostile thenable rejection); + * ordinary script failures arrive pre-rendered via {@link thrownRendering}. * @param error - the thrown value, of any shape and any realm. * @returns human-readable text for the failure report; prefers the stack. */ @@ -86,24 +136,18 @@ export function describeThrown(error: unknown): string { } /** - * Read `error.stack`, tolerating both descriptor shapes: an own DATA property - * (older V8, plain objects) and the modern own ACCESSOR pair (the Error Stack - * Accessor proposal). Invoking the getter is the only way to obtain a real - * stack; on a hostile object that getter is user code, so the call is - * contained — a throw yields `undefined` (the caller falls back to message), - * and a synchronous spin is the engine's already-accepted post-await - * limitation (a script can spin directly just the same). + * Read `error.stack` without running foreign code: an own DATA descriptor is + * read directly; an accessor is invoked only on function identity with + * {@link HOST_STACK_GETTER} (never a realm or user function). The native + * getter returns `undefined` on a non-Error receiver rather than throwing. */ function readStack(error: object): unknown { const descriptor = Object.getOwnPropertyDescriptor(error, 'stack') if (descriptor === undefined) return undefined if ('value' in descriptor) return descriptor.value if (typeof descriptor.get !== 'function') return undefined - try { - return descriptor.get.call(error) - } catch { - return undefined // a hostile stack getter threw; message/fallback renders instead - } + if (descriptor.get !== HOST_STACK_GETTER) return undefined + return descriptor.get.call(error) } /** An own DATA property's value (`undefined` for absent or accessor); never invokes user code on a non-proxy object. */ diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index c108d2cf69..892b7c781d 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -41,7 +41,7 @@ import type { WorkflowMeta, WorkflowResult, } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError, describeThrown } from './realm.ts' +import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering, REALM_THROWN_RENDERER_SOURCE } from './realm.ts' /** The per-run knobs the engine resolves from its Config. */ export interface ExecutionLimits { @@ -137,13 +137,19 @@ export class WorkflowExecution { ) { // Compile FIRST: a body syntax error must throw out of the constructor // (the engine maps it to SCRIPT_PARSE) before any realm state exists. + // The body is wrapped in a realm-side catch that pre-renders any thrown + // value to a string (see REALM_THROWN_RENDERER_SOURCE) — rendering happens + // inside the realm's own execution window, never on a host catch path. // lineOffset compensates for the wrapper line, so stack traces carry the // script's own line numbers (the meta statement was blanked, not removed). try { - this.compiled = new vm.Script(`(async () => {\n${body}\n})()`, { - filename: `workflow:${meta.name}`, - lineOffset: -1, - }) + this.compiled = new vm.Script( + `(async () => { try {\n${body}\n} catch (e) { throw (${REALM_THROWN_RENDERER_SOURCE})(e) } })()`, + { + filename: `workflow:${meta.name}`, + lineOffset: -1, + }, + ) } catch (error: unknown) { throw new WorkflowError(`workflow script does not parse: ${String(error)}`, 'SCRIPT_PARSE', { cause: error }) } @@ -225,10 +231,13 @@ export class WorkflowExecution { if (error instanceof WorkflowError && error.code === 'CANCELLED') { return { value: null, stopReason: 'cancelled', error: error.message, agentsStarted: this.started } } - // describeThrown is total and trap-free: a hostile thrown value (a - // throwing accessor, a proxy) cannot make this catch throw — drive() - // resolving is the `result` never-rejects seam contract. - return { value: null, stopReason: 'error', error: describeThrown(error), agentsStarted: this.started } + // Ordinary script failures arrive pre-rendered by the realm-side catch + // (thrownRendering); host-thrown errors (a vm timeout, a WorkflowError) + // and adversarial values that bypassed the wrapper (e.g. a hostile + // thenable rejection) render via the total, host-code-only + // describeThrown. Neither path can throw — drive() resolving is the + // `result` never-rejects seam contract. + return { value: null, stopReason: 'error', error: thrownRendering(error) ?? describeThrown(error), agentsStarted: this.started } } finally { // Reap strays: a script that fired agent() calls without awaiting them // leaves live children behind after settlement — abort them all. (The diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-vm/tests/meta.spec.ts index 7b5a929046..a957b0ae05 100644 --- a/packages/workflow/workflow-vm/tests/meta.spec.ts +++ b/packages/workflow/workflow-vm/tests/meta.spec.ts @@ -116,11 +116,24 @@ return 2` expect(error.message).toContain('proxies cannot cross') }) - it('a meta expression THROWING a hostile value maps to META_INVALID — rendering runs no realm code', () => { + it('a meta expression THROWING a hostile value maps to META_INVALID — rendering stays realm-side', () => { + // bad() rethrows anything that is not a WorkflowError, so a hostile value + // escaping the realm-side renderer raw would fail this test. const error = bad('export const meta = { name: (() => { throw { get stack() { throw new Error("boom") }, toString() { throw new Error("boom") } } })(), description: "d" }\nreturn 1') expect(error.code).toBe('META_INVALID') expect(error.message).toContain('pure literal') - expect(error.message).toContain('[object Object]') + expect(error.message).toContain('[unrenderable thrown value]') + }) + + it('a spinning meta expression (even inside a thrown stack getter) dies by the eval timeout', () => { + try { + extractMeta('export const meta = { name: (() => { while (true) {} })(), description: "d" }', 50) + throw new Error('expected the extraction to time out') + } catch (error: unknown) { + expect(error).toBeInstanceOf(WorkflowError) + expect((error as WorkflowError).code).toBe('META_INVALID') + expect((error as WorkflowError).message.toLowerCase()).toContain('timed out') + } }) it('rejects shape violations with EVERY violation listed (META_INVALID)', () => { diff --git a/packages/workflow/workflow-vm/tests/realm.spec.ts b/packages/workflow/workflow-vm/tests/realm.spec.ts index 86deb49bd3..c1bdeb33d6 100644 --- a/packages/workflow/workflow-vm/tests/realm.spec.ts +++ b/packages/workflow/workflow-vm/tests/realm.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' import * as vm from 'node:vm' -import { materializeFromRealm, MaterializeError } from '../src/realm.ts' +import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering } from '../src/realm.ts' /** Evaluate an expression inside a fresh vm realm and hand back the raw realm value. */ function inRealm(expression: string): unknown { @@ -133,3 +133,46 @@ describe('materializeFromRealm', () => { expect(materializeFromRealm(null)).toBeNull() }) }) + +describe('describeThrown (host-side thrown-value rendering)', () => { + it('renders a HOST Error via its identity-verified native stack getter', () => { + const error = new Error('host failure') + const rendered = describeThrown(error) + expect(rendered).toContain('host failure') + expect(rendered).toContain('at ') // a real stack, not just the message + }) + + it('never invokes a REALM error stack getter (identity mismatch) — message renders instead', () => { + const realmError: unknown = vm.runInNewContext('(() => { try { throw new Error("realm failure") } catch (e) { return e } })()') + expect(describeThrown(realmError)).toBe('realm failure') + }) + + it('reads a data-property stack directly and falls through a setter-only accessor', () => { + expect(describeThrown({ stack: 'data stack' })).toBe('data stack') + const setterOnly = { message: 'via message' } + Object.defineProperty(setterOnly, 'stack', { set() { /* swallow */ } }) + expect(describeThrown(setterOnly)).toBe('via message') + }) + + it('labels proxies and functions without touching them; primitives stringify', () => { + expect(describeThrown(new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('trap ran') } }))).toBe('[thrown proxy]') + expect(describeThrown(() => 1)).toBe('[thrown function]') + expect(describeThrown('plain')).toBe('plain') + expect(describeThrown(42)).toBe('42') + expect(describeThrown(undefined)).toBe('undefined') + expect(describeThrown(null)).toBe('null') + expect(describeThrown({ code: 42 })).toBe('[object Object]') + }) +}) + +describe('thrownRendering (the realm-catch wrapper reader)', () => { + it('extracts the pre-rendered string from a wrapper and nothing else', () => { + expect(thrownRendering({ __wfThrown: 'rendered text' })).toBe('rendered text') + expect(thrownRendering({ __wfThrown: 42 })).toBeUndefined() + expect(thrownRendering({ other: 'x' })).toBeUndefined() + expect(thrownRendering(new Error('plain'))).toBeUndefined() + expect(thrownRendering('string')).toBeUndefined() + expect(thrownRendering(null)).toBeUndefined() + expect(thrownRendering(new Proxy({ __wfThrown: 'forged' }, { getOwnPropertyDescriptor() { throw new Error('trap ran') } }))).toBeUndefined() + }) +}) diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index e0518c8192..00a9438575 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -589,24 +589,24 @@ describe('dsh-workflow-vm', () => { expect(result.error).toBe('[object Object]') }) - it('hostile thrown values render contained: result NEVER rejects, no unhandled rejection', async () => { + it('hostile thrown values render realm-side: result NEVER rejects, no unhandled rejection', async () => { const unhandled: unknown[] = [] const onUnhandled = (reason: unknown): void => { unhandled.push(reason) } process.on('unhandledRejection', onUnhandled) try { const { ctx, parent } = await setup() - // Each thrown value would run realm code (or throw) under a plain - // property read or String(); rendering must stay total — the only - // permitted realm call is the CONTAINED stack getter. + // Each thrown value runs code (or throws) when rendered — the realm + // wrapper renders it INSIDE script execution, and the host catch only + // ever descriptor-reads the pre-rendered string. const cases: [string, string][] = [ ["throw { get stack() { throw new Error('stack getter threw') } }", '[object Object]'], ["throw { get stack() { throw new Error('x') }, message: 'getter threw, message renders' }", 'getter threw, message renders'], - ["throw { get message() { throw new Error('message getter ran') } }", '[object Object]'], + ["throw { get message() { throw new Error('message getter threw') } }", '[object Object]'], ["throw { stack: 'custom data stack' }", 'custom data stack'], ["throw (() => { const o = { message: 'setter-only stack' }; Object.defineProperty(o, 'stack', { set() {} }); return o })()", 'setter-only stack'], - ["throw new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('trap ran') } })", '[thrown proxy]'], - ["throw { [Symbol.toPrimitive]() { throw new Error('toPrimitive ran') } }", '[object Object]'], - ['throw () => 1', '[thrown function]'], + ["throw new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('gopd trap threw') } })", '[object Object]'], + ["throw { [Symbol.toPrimitive]() { throw new Error('toPrimitive threw') } }", '[unrenderable thrown value]'], + ['throw () => 1', '() => 1'], ['throw null', 'null'], ] for (const [body, rendered] of cases) { @@ -622,6 +622,27 @@ describe('dsh-workflow-vm', () => { } }) + it('a synchronous spin hidden in a thrown stack getter dies by the vm timeout, not on the host', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', syncTimeoutMs: 50 } }) + // The realm-side renderer reads e.stack INSIDE the timed sync slice, so + // the spin is killed exactly like a plain `while (true) {}` body. + const result = await run(ctx, parent, script('throw { get stack() { while (true) {} } }')) + expect(result.stopReason).toBe('error') + expect(result.error?.toLowerCase()).toContain('timed out') + }) + + it('a hostile thenable rejection that bypasses the realm wrapper renders host-side, data-only', async () => { + const { ctx, parent } = await setup() + // Returning a thenable makes the host unwrap it AFTER the script + // settled — its rejection value skips the realm catch entirely and hits + // drive()'s catch raw. The proxy must be labelled, its traps never run. + const result = await run(ctx, parent, script(` + return { then(_resolve, reject) { reject(new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('trap ran') } })) } } + `)) + expect(result.stopReason).toBe('error') + expect(result.error).toBe('[thrown proxy]') + }) + it('falls back to the message for an Error whose stack was stripped', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` From 95c8c878e1e967b9be6e306593d845e21e6ed30e Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 20:57:51 +0800 Subject: [PATCH 009/119] workflow: pin thenable-return semantics as documented async-JS behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex code-review round 4 flagged the return channel: an async IIFE Promise-assimilates a returned thenable, so its then() runs past the sync slice and the RESOLUTION replaces the raw object. Verified against the real engine and judged behavior, not defect: - Assimilation is standard JavaScript (an async function's returned thenable resolves before the caller sees it) and is load-bearing ergonomics: an un-awaited 'return agent(...)' / 'return parallel(...)' resolves to the intended value precisely because of it. Rejecting callable-then returns would break that; intercepting pre-assimilation is spec-impossible (the Get(v,'then') and job enqueue are internal to promise resolution). - The realm-boundary guard applies to the RESOLUTION (a thenable resolving to non-JSON is still RESULT_UNSERIALIZABLE), so nothing crosses unmaterialized. - A spin inside a returned thenable's then() is the same accepted class as any post-slice spin (it runs on the microtask queue, past the vm timeout's reach); the docs previously said 'after the first await', which was too narrow — reworded to 'past the initial synchronous slice (an await continuation, or a thenable's then invoked by promise resolution)'. Pinned with an engine test (un-awaited return agent(); custom thenable resolution as the return value; thenable resolving to non-JSON rejects), and the limitation wording updated in the module doc, README, and RFC. --- .../feature/2026-07-05-dynamic-workflows.md | 2 +- packages/workflow/workflow-vm/README.md | 2 +- packages/workflow/workflow-vm/src/index.ts | 18 +++++++++++------- .../workflow-vm/tests/workflow-vm.spec.ts | 13 +++++++++++++ 4 files changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 6f8678ecea..f44e1fad89 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -24,7 +24,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre ### The engine (dsh-workflow-vm): in-process node:vm -**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Scripts are model-written — the same trust level as the model's existing bash access — so genuine sandboxing is not the current requirement. The interface/implementation split exists precisely so a hardened engine can swap in later. Accepted, documented limitations: vm is not a security boundary, and the vm timeout covers only the initial synchronous slice — a pathological synchronous spin after the first await cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. +**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Scripts are model-written — the same trust level as the model's existing bash access — so genuine sandboxing is not the current requirement. The interface/implementation split exists precisely so a hardened engine can swap in later. Accepted, documented limitations: vm is not a security boundary, and the vm timeout covers only the initial synchronous slice — a pathological synchronous spin in realm code past that slice (an await continuation, or a thenable's `then` invoked by promise resolution — a returned thenable resolves per JavaScript semantics, which is what makes an un-awaited `return agent('x')` work) cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. **Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index e519ce7c0e..05a8e252d3 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -16,7 +16,7 @@ Values ENTERING the host (the meta literal, hook options/schemas, the script's r Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). Thrown script values are pre-rendered to a string INSIDE the realm's execution window (the body is compiled into a realm-side catch), so a hostile `stack` getter is subject to the vm sync-slice timeout like any other script code; the host catch only descriptor-reads that string, falling back to `describeThrown` (fixed labels, own-data reads, an identity-verified host-native stack getter) — `result` cannot reject. -**Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin after the first await cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). +**Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin in realm code past that slice (an await continuation, or a thenable's `then` invoked by promise resolution) cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). A returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — and the realm-boundary guard applies to the resolution. ## Config diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-vm/src/index.ts index 4f6a506329..d0c8d8abfc 100644 --- a/packages/workflow/workflow-vm/src/index.ts +++ b/packages/workflow/workflow-vm/src/index.ts @@ -12,13 +12,17 @@ * level as the model's bash access — and the realm-boundary materialization * is correctness containment, not a sandbox. * - The vm `timeout` covers only the initial SYNCHRONOUS slice of the script; - * a pathological synchronous spin after the first await cannot be killed - * in-process. `dispose()` waits a bounded grace for the script to settle - * AND its children (stray `agent()` calls included) to finish disposing, - * then ABANDONS whatever is left: pending hook promises are already - * rejected and the script's settlement is contained (no unhandled - * rejection), but an abandoned synchronous spin would still occupy the - * event loop. + * realm code that runs past that slice — an await continuation, a + * thenable's `then` invoked by promise resolution (including one the script + * RETURNS: a returned thenable resolves per JavaScript semantics before + * materialization, which is what makes an un-awaited `return agent('x')` + * work) — is beyond the timeout, so a pathological synchronous spin there + * cannot be killed in-process. `dispose()` waits a bounded grace for the + * script to settle AND its children (stray `agent()` calls included) to + * finish disposing, then ABANDONS whatever is left: pending hook promises + * are already rejected and the script's settlement is contained (no + * unhandled rejection), but an abandoned synchronous spin would still + * occupy the event loop. * * Plugin export shape: a default-exported {@link WorkflowService} subclass * (the class-based service form, like `dsh-bash-local`). diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index 00a9438575..28c67dda14 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -217,6 +217,19 @@ describe('dsh-workflow-vm', () => { expect(result.stopReason).toBe('completed') expect(result.value).toBeNull() }) + + it('a returned promise/thenable resolves per async-JS semantics before materialization', async () => { + const { ctx, parent } = await setup() + // Load-bearing ergonomics: forgetting await on the final hook call works. + expect((await run(ctx, parent, script("return agent('x')"))).value).toBe('stub reply') + // A hand-built thenable is assimilated by the async return — the + // RESOLUTION is the script's return value (standard JavaScript), and the + // realm-boundary guard applies to that resolution, not the thenable. + expect((await run(ctx, parent, script('return { value: 1, then(resolve) { resolve({ ok: true }) } }'))).value).toEqual({ ok: true }) + const nonJson = await run(ctx, parent, script('return { then(resolve) { resolve({ bad: new Date(0) }) } }')) + expect(nonJson.stopReason).toBe('error') + expect(nonJson.error).toContain('not plain JSON data') + }) }) describe('combinator semantics', () => { From 7234d41b915d0b75e7b69ee1b99e42fa002e7e4b Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 5 Jul 2026 21:24:30 +0800 Subject: [PATCH 010/119] workflow: hook promises and hook failures are realm-built too MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex code-review round 5: agent()/parallel()/pipeline() returned HOST Promise objects into the script realm — Object.getPrototypeOf(agent('x')) reached host Promise.prototype, contradicting the realm contract (correctness containment, not the accepted sandbox stance). The rejection channel had the same leak one hop away: a caught hook failure was a host WorkflowError (host Error.prototype chain), and phase()/log() threw host errors synchronously. All three surfaces are realm-built now: - hook promises: the realm's own Promise.resolve (bound at context setup) assimilates the host promise, so the script-visible promise carries realm prototypes; the realm promise gets the same no-op rejection consumer as the host one (a script may drop it). - hook failures: rejections and phase/log sync throws are translated at the boundary into realm-built clones (name/code/message/fatal via an in-realm factory); non-WorkflowError host failures become generic realm Errors carrying their describeThrown rendering. - the combinators recognize FATAL clones structurally (isFatalWorkflowErrorClone: proxy-guarded descriptor reads), preserving the fatal-vs-null discipline across the boundary; a script forging the shape kills only its own run. drive() maps any post-cancel failure to 'cancelled' by run state (a CANCELLED clone deliberately fails the host instanceof). Tests: realm-promise identity for all three hooks + host Promise.prototype pollution unreachable; clone shape (instanceof realm Error, name/code/fatal/ message) with prototype-chain mutation staying realm-side; a rejecting provider result crossing as a generic clone; phase/log sync-throw clones; combinator catch branches (string throw, proxy throw, shape-miss forgery → null; forged fatal → kills own run); existing fatal-propagation, cancellation, and unhandled-rejection tests as canaries. --- .../feature/2026-07-05-dynamic-workflows.md | 2 +- packages/workflow/workflow-vm/README.md | 2 +- packages/workflow/workflow-vm/src/realm.ts | 16 +++ packages/workflow/workflow-vm/src/runtime.ts | 112 ++++++++++++++---- .../workflow-vm/tests/workflow-vm.spec.ts | 96 ++++++++++++++- 5 files changed, 203 insertions(+), 25 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index f44e1fad89..4d7061335e 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -28,7 +28,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre **Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. -**Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, proxies included (the trap-free `util.types.isProxy`, checked before any inspection, so realm-side traps never run on the host stack), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm (`args`, `agent()` results) are rebuilt INSIDE the realm via the context's own `JSON.parse`, and `parallel`/`pipeline` resolve to realm-built arrays, so the script never holds a live host-prototype object. Realm functions (stages, thunks) are called, never materialized. +**Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, proxies included (the trap-free `util.types.isProxy`, checked before any inspection, so realm-side traps never run on the host stack), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm are realm-built throughout, so the script never holds a live host-prototype object: `args` and `agent()` results via the context's own `JSON.parse`, combinator result arrays via its `Array.from`, hook promises via its `Promise.resolve`, and hook failures as realm-built clones (name/code/message/fatal — the combinators recognize fatal clones structurally). Realm functions (stages, thunks) are called, never materialized. **Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Thrown script/meta values are pre-rendered to a string by a realm-side catch compiled into the wrapper (rendering runs inside the realm's own execution window, so a hostile `stack` getter dies by the vm sync-slice timeout like any other script code — host-side formatting of realm errors is unfixable in general, since V8 stack formatting invokes script-controllable `name`/`prepareStackTrace` hooks); the host catch descriptor-reads that string or falls back to `describeThrown` (fixed labels, own-data reads, an identity-verified host-native stack getter), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index 05a8e252d3..b5d8817735 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -10,7 +10,7 @@ The first [`WorkflowService`](../workflow/README.md) implementation: an in-proce ## Realm discipline -Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a descriptor walk that never invokes accessors and rejects loud everything JSON cannot carry (accessors, exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`, and proxies — rejected via the trap-free `util.types.isProxy` BEFORE any inspection could run a realm-side trap on the host stack), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values ENTERING the realm (`args`, `agent()` results) are rebuilt INSIDE the realm through the context's own `JSON.parse`, and the arrays `parallel`/`pipeline` resolve to are realm-built, so the script never holds an object whose prototype chain reaches host intrinsics. +Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a descriptor walk that never invokes accessors and rejects loud everything JSON cannot carry (accessors, exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`, and proxies — rejected via the trap-free `util.types.isProxy` BEFORE any inspection could run a realm-side trap on the host stack), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values ENTERING the realm are realm-built throughout, so the script never holds an object whose prototype chain reaches host intrinsics: `args` and `agent()` results are rebuilt through the context's own `JSON.parse`, combinator result arrays through its `Array.from`, hook promises through its `Promise.resolve`, and a hook failure (rejection or synchronous `phase`/`log` throw) crosses as a realm-built clone carrying name/code/message/fatal — the combinators recognize fatal clones structurally, so the fatal-vs-null discipline survives the boundary. ## Limits, cancellation, disposal diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts index fca93caac4..c1f1ff7c5c 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -156,6 +156,22 @@ function ownDataProperty(value: object, key: string): unknown { return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined } +/** + * Whether `error` is a FATAL realm-built `WorkflowError` clone — the shape the + * engine's hooks reject with (host errors are translated at the realm boundary + * so the script never holds host prototypes), duck-checked because a realm + * object cannot be an `instanceof` the host class. Proxy-guarded and + * descriptor-read, so a forged object cannot run code here; a script forging + * the shape only kills its own run (self-sabotage). Combinators use this to + * decide re-throw vs per-item `null`. + * @param error - the value a combinator caught from a realm thunk/stage. + * @returns `true` when the error must propagate and kill the script. + */ +export function isFatalWorkflowErrorClone(error: unknown): boolean { + if (typeof error !== 'object' || error === null || types.isProxy(error)) return false + return ownDataProperty(error, 'name') === 'WorkflowError' && ownDataProperty(error, 'fatal') === true +} + /** * Whether an object's prototype chain is data-shaped: `null`, or a prototype * whose own prototype is `null` (the realm's `Object.prototype` — which we diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index 892b7c781d..955be94a87 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -9,17 +9,22 @@ * descriptor walks; values ENTERING the realm from the host (`args`, agent() * results) are rebuilt INSIDE the realm through the context's own * `JSON.parse`, so the script never holds an object whose prototype chain - * reaches host intrinsics. The arrays `parallel`/`pipeline` resolve to are - * realm-built for the same reason (their ELEMENTS are realm values already — - * only the container needs rebuilding). Realm functions (pipeline stages, - * parallel thunks) are called, not materialized — their values stay - * realm-side. + * reaches host intrinsics. The same rule covers every other value a hook + * hands the script: the promises `agent`/`parallel`/`pipeline` return are + * realm promises (the realm's own `Promise.resolve` over the host promise), + * the arrays the combinators resolve to are realm-built (their ELEMENTS are + * realm values already — only the container needs rebuilding), and a hook + * failure — rejection or synchronous `phase`/`log` throw — crosses as a + * realm-built clone carrying name/code/message/fatal. Realm functions + * (pipeline stages, parallel thunks) are called, not materialized — their + * values stay realm-side. * * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments, * unsupported options/schemas, tripped caps, seam start failures, - * cancellation) ALWAYS propagate through `parallel`/`pipeline`; the per-item - * `null` is reserved for child-run failures and ordinary in-stage script - * errors. Every hook-returned promise gets a no-op rejection consumer + * cancellation) ALWAYS propagate through `parallel`/`pipeline` — they cross + * the realm boundary as fatal clones, recognized structurally — and the + * per-item `null` is reserved for child-run failures and ordinary in-stage + * script errors. Every hook-returned promise gets a no-op rejection consumer * attached, so a script that drops a promise (fires an `agent()` without * awaiting it) cannot surface an unhandled rejection when cancellation * rejects it — the app boot layer exits the process on unhandled rejections. @@ -34,14 +39,14 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-subagent' import { assertSupportedOutputSchema, OutputSchemaError } from '@deepseek-ai/dsh-tools' import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' -import { WorkflowError, isFatalWorkflowError } from '@deepseek-ai/dsh-workflow' +import { WorkflowError } from '@deepseek-ai/dsh-workflow' import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowMeta, WorkflowResult, } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering, REALM_THROWN_RENDERER_SOURCE } from './realm.ts' +import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering, isFatalWorkflowErrorClone, REALM_THROWN_RENDERER_SOURCE } from './realm.ts' /** The per-run knobs the engine resolves from its Config. */ export interface ExecutionLimits { @@ -121,6 +126,8 @@ export class WorkflowExecution { private readonly context: vm.Context private readonly realmJsonParse: (text: string) => unknown private readonly realmArrayFrom: (items: unknown[]) => unknown[] + private readonly realmPromiseResolve: (value: unknown) => Promise + private readonly realmErrorClone: (name: string, code: string | undefined, message: string, fatal: boolean) => unknown private readonly compiled: vm.Script /** Every live `agent()` call promise — awaited or stray — for {@link quiesce}. */ private readonly inFlightAgents = new Set>() @@ -159,16 +166,38 @@ export class WorkflowExecution { // The realm's own JSON.parse — the host→realm rebuild channel. const realmJson = vm.runInContext('JSON', this.context) as { parse(text: string): unknown } this.realmJsonParse = (text: string) => realmJson.parse(text) - // The realm's own Array.from, bound NOW so a script reassigning its - // globals later cannot swap it: combinator results must be realm arrays. + // The realm's own Array.from / Promise.resolve / an error factory, bound + // NOW so a script reassigning its globals later cannot swap them: + // combinator results must be realm arrays, hook promises realm promises, + // and hook failures realm-built clones. this.realmArrayFrom = vm.runInContext('Array.from.bind(Array)', this.context) as (items: unknown[]) => unknown[] + this.realmPromiseResolve = vm.runInContext('Promise.resolve.bind(Promise)', this.context) as (value: unknown) => Promise + this.realmErrorClone = vm.runInContext(`(name, code, message, fatal) => { + const error = new Error(message) + error.name = name + if (code !== undefined) error.code = code + error.fatal = fatal + return error + }`, this.context) as (name: string, code: string | undefined, message: string, fatal: boolean) => unknown const globals: Record = { - agent: (prompt: unknown, opts?: unknown) => this.contain(this.track(this.agent(prompt, opts))), - parallel: (thunks: unknown) => this.contain(this.parallel(thunks)), - pipeline: (items: unknown, ...stages: unknown[]) => this.contain(this.pipeline(items, stages)), - phase: (title: unknown) => { this.phase(title) }, - log: (message: unknown) => { this.log(message) }, + agent: (prompt: unknown, opts?: unknown) => this.realmFacing(this.track(this.agent(prompt, opts))), + parallel: (thunks: unknown) => this.realmFacing(this.parallel(thunks)), + pipeline: (items: unknown, ...stages: unknown[]) => this.realmFacing(this.pipeline(items, stages)), + phase: (title: unknown) => { + try { + this.phase(title) + } catch (error: unknown) { + throw this.toRealmError(error) + } + }, + log: (message: unknown) => { + try { + this.log(message) + } catch (error: unknown) { + throw this.toRealmError(error) + } + }, args: this.toRealm(args), } for (const [key, value] of Object.entries(globals)) { @@ -228,8 +257,12 @@ export class WorkflowExecution { const value = raw === undefined ? null : this.materializeResult(raw) return { value, stopReason: 'completed', agentsStarted: this.started } } catch (error: unknown) { - if (error instanceof WorkflowError && error.code === 'CANCELLED') { - return { value: null, stopReason: 'cancelled', error: error.message, agentsStarted: this.started } + // Any failure after cancel() reports `cancelled` with the canonical + // reason — the reject path mirrors the resolve path's post-settle + // check, and a hook CANCELLED failure crosses the realm boundary as a + // clone that deliberately fails the host `instanceof`. + if (this.isCancelled()) { + return { value: null, stopReason: 'cancelled', error: this.cancelledError().message, agentsStarted: this.started } } // Ordinary script failures arrive pre-rendered by the realm-side catch // (thrownRendering); host-thrown errors (a vm timeout, a WorkflowError) @@ -258,6 +291,37 @@ export class WorkflowExecution { return promise } + /** + * Hand a hook's host promise to the script as a REALM promise (the realm's + * own `Promise.resolve` assimilates it) whose failure reason is a + * realm-built clone — the script must never hold host prototypes, and both + * the promise object and a caught rejection would otherwise expose them + * (module doc). The realm promise gets the same no-op rejection consumer as + * {@link contain}, since the script may drop it; the intermediate host + * promises are handled by the assimilation chain itself. + */ + private realmFacing(hostPromise: Promise): Promise { + const translated = hostPromise.catch((error: unknown) => { + throw this.toRealmError(error) + }) + const realmPromise = this.realmPromiseResolve(translated) + realmPromise.catch(() => { /* consumed: a script-dropped realm promise must not surface an unhandled rejection (see contain) */ }) + return realmPromise + } + + /** + * Rebuild a host failure as a realm-built error clone: a `WorkflowError` + * keeps its name/code/message/fatal (the combinators recognize the shape + * via {@link isFatalWorkflowErrorClone}); anything else becomes a generic + * realm `Error` carrying its {@link describeThrown} rendering. + */ + private toRealmError(error: unknown): unknown { + if (error instanceof WorkflowError) { + return this.realmErrorClone('WorkflowError', error.code, error.message, error.fatal) + } + return this.realmErrorClone('Error', undefined, describeThrown(error), false) + } + /** * Register one `agent()` call promise for {@link quiesce} tracking; the * entry drops when the call fully settles (which is AFTER its child's @@ -472,7 +536,10 @@ export class WorkflowExecution { try { return await thunk() } catch (error: unknown) { - if (isFatalWorkflowError(error)) throw error + // Hooks translate host errors at the realm boundary, so a fatal error + // reaches a thunk catch only as a realm clone (a script forging the + // shape merely kills its own run). + if (isFatalWorkflowErrorClone(error)) throw error return null } })) @@ -505,8 +572,9 @@ export class WorkflowExecution { return value } catch (error: unknown) { // An ordinary stage throw drops the ITEM to null and skips its - // remaining stages; a fatal error kills the whole script. - if (isFatalWorkflowError(error)) throw error + // remaining stages; a fatal error (a realm clone — see parallel()) + // kills the whole script. + if (isFatalWorkflowErrorClone(error)) throw error return null } })) diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index 28c67dda14..d87d571295 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -288,9 +288,23 @@ describe('dsh-workflow-vm', () => { () => { throw new Error('boom') }, () => agent('fine'), () => 'plain value', + () => { throw 'string throw' }, + () => { throw new Proxy({ name: 'WorkflowError', fatal: true }, {}) }, + () => { throw { name: 'WorkflowError', fatal: 'forged-but-not-true' } }, ]) `)) - expect(result.value).toEqual([null, 'stub reply', 'plain value']) + // The last three probe the fatal-clone recognition: a non-object, a + // proxy (never inspected), and a shape miss are all ordinary nulls. + expect(result.value).toEqual([null, 'stub reply', 'plain value', null, null, null]) + }) + + it('a script forging a fatal clone kills only its own run (self-sabotage, not a bypass)', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + return await parallel([() => { throw { name: 'WorkflowError', fatal: true, message: 'forged fatal' } }]) + `)) + expect(result.stopReason).toBe('error') + expect(result.error).toContain('forged fatal') }) it('FATAL errors propagate through parallel AND pipeline instead of dissolving into null', async () => { @@ -433,6 +447,86 @@ describe('dsh-workflow-vm', () => { expect((await run(ctx, parent, script('return typeof args'))).value).toBe('undefined') }) + it('hook promises are REALM promises: instanceof holds in-script, host Promise.prototype stays unreachable', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + const p = agent('x') + const par = parallel([() => 'v']) + const pipe = pipeline([1], (n) => n) + Object.getPrototypeOf(p).wfLeakProbe = 'realm-only' + return { + agentIsRealmPromise: p instanceof Promise, + parallelIsRealmPromise: par instanceof Promise, + pipelineIsRealmPromise: pipe instanceof Promise, + value: await p, + } + `)) + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ + agentIsRealmPromise: true, + parallelIsRealmPromise: true, + pipelineIsRealmPromise: true, + value: 'stub reply', + }) + expect((Promise.prototype as unknown as Record).wfLeakProbe).toBeUndefined() + delete (Promise.prototype as unknown as Record).wfLeakProbe + }) + + it('hook failures cross the boundary as realm-built WorkflowError clones', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + try { + await agent('p', { bogus: true }) + return 'unreachable' + } catch (e) { + Object.getPrototypeOf(Object.getPrototypeOf(e)).wfErrLeakProbe = 'realm-only' + return { isRealmError: e instanceof Error, name: e.name, code: e.code, fatal: e.fatal, message: e.message } + } + `)) + expect(result.stopReason).toBe('completed') + expect(result.value).toMatchObject({ isRealmError: true, name: 'WorkflowError', code: 'UNSUPPORTED_OPTION', fatal: true }) + expect((result.value as { message: string }).message).toContain('"bogus" is not recognized') + // The script mutated its error's prototype CHAIN — host intrinsics untouched. + expect((Object.prototype as unknown as Record).wfErrLeakProbe).toBeUndefined() + expect((Error.prototype as unknown as Record).wfErrLeakProbe).toBeUndefined() + }) + + it('a non-WorkflowError host failure (a rejecting provider result) crosses as a generic realm clone', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + const provider: SubagentProvider = { + name: 'rejecting', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + start: () => ({ + id: AgentId('reject-child'), + result: Promise.reject(new Error('backend exploded')), + cancel: () => { /* nothing in flight */ }, + dispose: () => Promise.resolve(), + }), + } + ctx.subagents.registerProvider(provider) + await ctx.plugin(VmWorkflowEngine, { provider: 'rejecting' }) + const result = await run(ctx, fakeParent(), script(` + try { await agent('p'); return 'unreachable' } catch (e) { return { isRealmError: e instanceof Error, name: e.name, message: e.message } } + `)) + expect(result.value).toMatchObject({ isRealmError: true, name: 'Error' }) + expect((result.value as { message: string }).message).toContain('backend exploded') + }) + + it('phase()/log() synchronous throws cross as realm clones too', async () => { + const { ctx, parent } = await setup() + const result = await run(ctx, parent, script(` + try { phase(3) } catch (e) { + if (!(e instanceof Error) || e.name !== 'WorkflowError') throw e + } + try { log(3) } catch (e) { + return { isRealmError: e instanceof Error, name: e.name, message: e.message } + } + `)) + expect(result.value).toMatchObject({ isRealmError: true, name: 'WorkflowError' }) + expect((result.value as { message: string }).message).toContain('log() requires') + }) + it('parallel/pipeline resolve to REALM arrays: instanceof holds in-script, host intrinsics stay unreachable', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` From 2accf85714885ae33fef40e58b30b3692f7ad3ec Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 00:48:49 +0800 Subject: [PATCH 011/119] workflow: simplify to the trust premise; settle result on cancellation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two review responses that belong together — the same review argued the engine was defending the wrong threat while a benign-input bug wedged the product. 1) Drop hostile-value containment; state the trust premise. Scripts are model-written — the same trust level as the model's bash access — yet successive pre-push review rounds had ratcheted in defenses that only matter against an adversarial author: trap-free proxy rejection, accessor-never-invoked descriptor walks, realm-side pre-rendering of thrown values, realm-built promises/arrays/error clones with structural fatal recognition. That same author keeps a documented, accepted, unkillable event-loop spin, so containing its error VALUES is cost without a threat model — and the planned hardened engine (worker/isolated-vm) gets value isolation by serialization and deletes all of this machinery anyway. What stays, because benign scripts hit it constantly: result never rejects; dropped hook promises cannot become unhandled rejections; the value boundary rejects LOUD everything JSON cannot carry (now a plain recursive walk — getters are read ordinarily and their result is what crosses; a throwing read fails loud); a "__proto__" key still copies as a data property; the fatal-vs-null combinator discipline (now host instanceof — unforgeable from the realm and simpler than clone-shape recognition). What changes for scripts (documented in the engine README): hooks hand back host values and host errors — in-script `instanceof Error` on a hook failure is false (branch on e.name/e.code) — and args are host-cloned once so a script cannot mutate the caller's object. realm.ts drops 289 → 173 lines; the hostile-value test tables go with it. The premise now leads the engine module doc, the README, and the RFC's engine section, with the removed machinery recorded under What was rejected. 2) result settles within the dispose grace of a cancellation. Review finding (verified through the real registry + tool + engine): a script parked on a promise no hook owns — `await new Promise(() => {})`, `await Promise.race([])`, a returned never-settling thenable — could not be settled by cancel(): hooks reject and children abort, but nothing touches a promise the engine does not own, so `result` stayed pending FOREVER (the previous cut even pinned that as intended). The tool awaits run.result BEFORE its disposing finally, the registry awaits the tool, the loop awaits the registry — one such script wedged the whole agent turn past any abort, unrecoverable in-process; the mock engine in the tool's abort test settles result on cancel, which is exactly the behavior the real engine lacked, so no existing test could see it. The seam contract now says it out loud: once a run is cancelled, result SETTLES within the implementation's bounded grace even if the script never does. The vm engine arms an abandon channel in cancel(); drive() races the script against it, force-settling 'cancelled' at the grace (the abandoned settlement stays contained; a post-slice synchronous spin remains the documented limitation). dispose()'s outer race now exists for child quiescence only, and `workflow/end` again fires exactly once per started run. The old 'result stays pending' pin is FLIPPED to the new contract (the pinned behavior was the bug); new regressions cover cancel-then-settle on a parked script, a never-settling returned thenable, and the full composition through the REAL registry + tool + vm engine (tool-workflow gains workflow-vm/subagent devDeps for it). agentsStarted JSDoc clarified while touching the vocabulary (accepted calls, including ones still queued at cancellation). --- docs/core-data-structures/workflow.md | 2 +- .../feature/2026-07-05-dynamic-workflows.md | 9 +- packages/workflow/tool-workflow/package.json | 2 + .../tool-workflow/tests/tool-workflow.spec.ts | 31 +++ packages/workflow/workflow-vm/README.md | 12 +- packages/workflow/workflow-vm/src/index.ts | 59 +++-- packages/workflow/workflow-vm/src/meta.ts | 15 +- packages/workflow/workflow-vm/src/realm.ts | 246 +++++------------- packages/workflow/workflow-vm/src/runtime.ts | 225 ++++++---------- .../workflow/workflow-vm/tests/meta.spec.ts | 20 +- .../workflow/workflow-vm/tests/realm.spec.ts | 99 +++---- .../workflow-vm/tests/workflow-vm.spec.ts | 208 ++++----------- packages/workflow/workflow/README.md | 2 +- packages/workflow/workflow/src/index.ts | 9 +- packages/workflow/workflow/src/types.ts | 16 +- pnpm-lock.yaml | 6 + 16 files changed, 352 insertions(+), 609 deletions(-) diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md index 11f216f39e..8c7916a6c3 100644 --- a/docs/core-data-structures/workflow.md +++ b/docs/core-data-structures/workflow.md @@ -47,7 +47,7 @@ interface WorkflowResult { ## A live run: `WorkflowRun` -The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — so the consumer maps a non-`completed` reason to an `isError` result. `dispose()` cancels, waits a bounded grace for the script to settle AND its children to finish disposing, then abandons whatever is left (the engine documents the abandonment semantics); it never hangs on a stuck script. +The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — and once the run is cancelled it SETTLES within the engine's bounded grace even if the script itself never settles (the engine abandons the script and reports `cancelled`), so a consumer awaiting `result` is never wedged past a cancellation. `dispose()` = cancel + that bounded settle + child quiescence (the engine documents what abandonment leaves behind); it never hangs on a stuck script. ```ts type-equiv interface WorkflowRun { diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 4d7061335e..f39f12f0ed 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -24,13 +24,13 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre ### The engine (dsh-workflow-vm): in-process node:vm -**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Scripts are model-written — the same trust level as the model's existing bash access — so genuine sandboxing is not the current requirement. The interface/implementation split exists precisely so a hardened engine can swap in later. Accepted, documented limitations: vm is not a security boundary, and the vm timeout covers only the initial synchronous slice — a pathological synchronous spin in realm code past that slice (an await continuation, or a thenable's `then` invoked by promise resolution — a returned thenable resolves per JavaScript semantics, which is what makes an un-awaited `return agent('x')` work) cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. +**Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) — host code MAY run script code while reading script values, and that is accepted, because a hostile script can already occupy the event loop forever with a synchronous spin past its first await; containing its error VALUES while conceding it the event loop would be cost without a threat model. Genuine hardening is an engine swap behind the seam (worker/isolated-vm gets value isolation by serialization for free), not incremental host-side defenses. + +**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Under the trust premise, in-process is enough. Accepted, documented limitations: `start()` blocks the caller for the script's initial synchronous slice (bounded by the vm timeout); that timeout covers ONLY the initial slice, so a synchronous spin past it (an await continuation, a thenable's `then` invoked by promise resolution — a returned thenable resolves per JavaScript semantics, which is what makes an un-awaited `return agent('x')` work — or script code the host runs while rendering a thrown value) cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. **Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. -**Realm boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a descriptor walk that NEVER invokes accessors (the repo's `isJsonValue` is prototype-strict and getter-invoking, so it cannot run first; it would reject every cross-realm object and let realm code run outside the timed window) and rejects loud everything JSON cannot carry, proxies included (the trap-free `util.types.isProxy`, checked before any inspection, so realm-side traps never run on the host stack), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values entering the realm are realm-built throughout, so the script never holds a live host-prototype object: `args` and `agent()` results via the context's own `JSON.parse`, combinator result arrays via its `Array.from`, hook promises via its `Promise.resolve`, and hook failures as realm-built clones (name/code/message/fatal — the combinators recognize fatal clones structurally). Realm functions (stages, thunks) are called, never materialized. - -**Containment**: every hook-returned promise carries a no-op rejection consumer, so a script that drops a promise cannot surface an unhandled rejection when cancellation rejects it — `dsh-app-boot` exits the process on unhandled rejections. Thrown script/meta values are pre-rendered to a string by a realm-side catch compiled into the wrapper (rendering runs inside the realm's own execution window, so a hostile `stack` getter dies by the vm sync-slice timeout like any other script code — host-side formatting of realm errors is unfixable in general, since V8 stack formatting invokes script-controllable `name`/`prepareStackTrace` hooks); the host catch descriptor-reads that string or falls back to `describeThrown` (fixed labels, own-data reads, an identity-verified host-native stack getter), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. +**Value boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation; getters are read ordinarily and their RESULT crosses (a throwing read fails loud). Values entering the realm (`args`, `agent()` results, hook promises and failures, combinator arrays) are handed over directly as host values — the script is trusted, so host prototypes are not a leak; `args` is host-`structuredClone`d once so a script cannot mutate the caller's object. Hook failures are host `WorkflowError`s: the combinators recognize fatality by host `instanceof` (unforgeable from the realm), and the script-visible consequence — in-script `instanceof Error` is `false` for hook errors; branch on `e.name`/`e.code` — is documented in the engine README. Realm functions (stages, thunks) are called, never materialized. Thrown script values are rendered by a total host-side renderer (stack → message → `String()`, fixed label if rendering throws), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. ### The consumer (dsh-tool-workflow) @@ -42,6 +42,7 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai ## What was rejected +- **Hostile-value containment in the host** (trap-free proxy rejection, accessor-never-invoked descriptor walks, realm-side pre-rendering of thrown values, realm-built promises/arrays/error clones with structural fatal recognition): an earlier revision built all of it, and review showed the cost was real while the threat model was not — every one of those defenses guards against an author the premise already trusts, who retains an accepted unkillable event-loop spin regardless. Removed in favor of the plain boundary above; the hardened engine deletes such machinery anyway (serialization by construction). - **Background execution as the default** (CC's shape): deferred; foreground-synchronous matches `dsh-tool-subagent`'s cut, and background semantics should be designed ONCE across bash/subagent/workflow rather than per-tool. - **Workflow-layer JSON parsing for `agent({schema})`**: duplicating a seam concern at one consumer while the seam's capability flag stayed dishonestly `false`. - **Meta as tool parameters instead of `export const meta`**: zero parsing, but scripts stop being self-contained artifacts and CC-authored scripts stop being drop-in. diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json index 9c3f819cb5..416b6a814f 100644 --- a/packages/workflow/tool-workflow/package.json +++ b/packages/workflow/tool-workflow/package.json @@ -35,9 +35,11 @@ "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-subagent": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-workflow": "workspace:^", + "@deepseek-ai/dsh-workflow-vm": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts index 012fae4961..677cbbf7a9 100644 --- a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts +++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts @@ -9,6 +9,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import { WorkflowRunId, WorkflowService } from '@deepseek-ai/dsh-workflow' import type { WorkflowResult, WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' import { CallId } from '@deepseek-ai/dsh-llm' +import SubagentService from '@deepseek-ai/dsh-subagent' +import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' import * as toolWorkflow from '../src/index.ts' /** A controllable engine standing in behind ctx.workflows (the tool's only seam). */ @@ -221,4 +223,33 @@ describe('dsh-tool-workflow', () => { expect(unwrapped).toBe(toolWorkflow) expect(typeof unwrapped.apply).toBe('function') }) + + describe('composition with the REAL vm engine (the mock above must stay honest)', () => { + it('an abort releases the tool even when the script parks on a promise no hook owns', async () => { + // Regression for the review-found turn wedge: the tool awaits + // run.result BEFORE its disposing finally, the registry and the loop + // await the tool — so if cancellation could not settle result (a script + // parked on `await new Promise(() => {})`), an aborted turn stayed + // wedged forever. The seam now guarantees result settles within the + // grace of cancel(); this drives that guarantee through the real + // registry + real tool + real engine. + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(SubagentService) + await ctx.plugin(VmWorkflowEngine, { disposeGraceMs: 30 }) + await ctx.plugin(toolWorkflow, {}) + const parent = { id: AgentId('caller'), options: {} } as unknown as Agent + const controller = new AbortController() + const pending = execute(ctx, { + script: "export const meta = { name: 'stuck', description: 'parks forever' }\nawait new Promise(() => {})\nreturn 1", + }, { agent: parent, signal: controller.signal }) + // Give the run a beat to start (past its synchronous slice), then abort. + await new Promise(resolve => setTimeout(resolve, 20)) + controller.abort('user abort') + const result = await pending + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('cancelled') + }) + }) }) diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index b5d8817735..0ec1116cb7 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -2,21 +2,25 @@ The first [`WorkflowService`](../workflow/README.md) implementation: an in-process **`node:vm` engine**. It parses the Claude Code-format script (`export const meta = {...}` + plain-JS body), runs the body in a fresh vm context with the workflow hooks injected, and fans `agent()` calls out to [`ctx.subagents`](../../subagent/README.md). +## Trust premise + +Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. vm is NOT a security boundary and no attempt is made to contain adversarial values: property reads on script values may run script code (a getter, a `toString`, a proxy trap) on the host stack, and a script determined to hang the process can simply spin past its first await (see the limitations below). What the engine DOES guarantee, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection (the app boot layer exits the process on those), values that JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing is an engine swap behind the seam (worker-thread/isolated-vm, where the boundary is serialization by construction), not incremental host-side defenses here. + ## The script contract it executes - **Meta extraction** (`extractMeta`): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. - **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline). - **Determinism bans**: `Date.now()`, `Math.random()`, and argless `new Date()` throw (kept even though resume is deferred, so scripts stay resume-compatible); no timers, filesystem, or Node APIs exist in the context. -## Realm discipline +## The value boundary -Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a descriptor walk that never invokes accessors and rejects loud everything JSON cannot carry (accessors, exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`, and proxies — rejected via the trap-free `util.types.isProxy` BEFORE any inspection could run a realm-side trap on the host stack), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Values ENTERING the realm are realm-built throughout, so the script never holds an object whose prototype chain reaches host intrinsics: `args` and `agent()` results are rebuilt through the context's own `JSON.parse`, combinator result arrays through its `Array.from`, hook promises through its `Promise.resolve`, and a hook failure (rejection or synchronous `phase`/`log` throw) crosses as a realm-built clone carrying name/code/message/fatal — the combinators recognize fatal clones structurally, so the fatal-vs-null discipline survives the boundary. +Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Getters are read ordinarily — the RESULT is what crosses; a read that throws fails loud. Values ENTERING the realm (`args`, `agent()` results, hook promises and their failures, combinator arrays) are handed over directly as host values — the script is trusted, so host prototypes are not a leak; `args` is `structuredClone`d once at start so a script scribbling on it cannot mutate the caller's object. One script-visible consequence: an error thrown by a hook is a HOST error, so `e instanceof Error` inside the script is `false` — branch on `e.name`/`e.code` instead (the combinators recognize fatality by host `instanceof`, which a script-built object can never pass, so fatal-vs-null cannot be forged or dissolved). ## Limits, cancellation, disposal -Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection (the app boot layer exits the process on those). Thrown script values are pre-rendered to a string INSIDE the realm's execution window (the body is compiled into a realm-side catch), so a hostile `stack` getter is subject to the vm sync-slice timeout like any other script code; the host catch only descriptor-reads that string, falling back to `describeThrown` (fixed labels, own-data reads, an identity-verified host-native stack getter) — `result` cannot reject. +Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks, and a script that STILL has not settled `disposeGraceMs` after the cancel (parked on a promise no hook owns, like `await new Promise(() => {})`) is ABANDONED with `result` force-settling `cancelled` — a consumer awaiting `result` is never wedged past a cancellation. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection; thrown script values are rendered by a total host-side renderer (stack, then message, then `String()`, with a fixed label if rendering itself throws) — `result` cannot reject. -**Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): vm is NOT a security boundary — scripts are model-written, the same trust level as the model's bash access — and the vm `timeout` covers only the initial synchronous slice, so a pathological synchronous spin in realm code past that slice (an await continuation, or a thenable's `then` invoked by promise resolution) cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). A returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — and the realm-boundary guard applies to the resolution. +**Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): `start()` runs the script's initial synchronous slice inline, so the caller blocks until the first await or the vm `timeout`; that `timeout` covers ONLY the initial slice, so a synchronous spin past it (an await continuation, a thenable's `then` invoked by promise resolution, or script code the host runs while rendering a thrown value) cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). A returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — and the value-boundary guard applies to the resolution. ## Config diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-vm/src/index.ts index d0c8d8abfc..9b8c646aa9 100644 --- a/packages/workflow/workflow-vm/src/index.ts +++ b/packages/workflow/workflow-vm/src/index.ts @@ -4,25 +4,33 @@ * body in a fresh in-process vm context with the workflow hooks injected, and * fans `agent()` calls out to `ctx.subagents`. * - * Engine limitations, documented as the accepted cost of the in-process - * mechanism (the interface/implementation seam exists precisely so a - * worker-thread or isolated-vm engine can swap in if these ever matter): + * TRUST PREMISE: scripts are MODEL-WRITTEN — the same trust level as the + * model's existing bash access — so this engine defends against BUGGY + * scripts, never hostile ones. vm is NOT a security boundary and no attempt + * is made to contain adversarial values (see ./realm.ts); genuine sandboxing + * is an engine swap behind the seam (worker-thread/isolated-vm), not + * incremental host-side defenses here. * - * - vm is NOT a security boundary. Scripts are model-written — the same trust - * level as the model's bash access — and the realm-boundary materialization - * is correctness containment, not a sandbox. - * - The vm `timeout` covers only the initial SYNCHRONOUS slice of the script; - * realm code that runs past that slice — an await continuation, a - * thenable's `then` invoked by promise resolution (including one the script - * RETURNS: a returned thenable resolves per JavaScript semantics before - * materialization, which is what makes an un-awaited `return agent('x')` - * work) — is beyond the timeout, so a pathological synchronous spin there - * cannot be killed in-process. `dispose()` waits a bounded grace for the - * script to settle AND its children (stray `agent()` calls included) to - * finish disposing, then ABANDONS whatever is left: pending hook promises - * are already rejected and the script's settlement is contained (no - * unhandled rejection), but an abandoned synchronous spin would still - * occupy the event loop. + * Engine limitations, documented as the accepted cost of the in-process + * mechanism: + * + * - `start()` runs the script's initial SYNCHRONOUS slice inline, so the + * CALLER blocks on the host event loop until the script's first await (or + * the vm `timeout` kills the slice); the meta-literal evaluation has its + * own timeout budget on the same call. + * - The vm `timeout` covers only that initial slice; realm code running past + * it — an await continuation, a thenable's `then` invoked by promise + * resolution (including one the script RETURNS: a returned thenable + * resolves per JavaScript semantics before materialization, which is what + * makes an un-awaited `return agent('x')` work) — is beyond the timeout, so + * a synchronous spin there cannot be killed in-process, and neither can + * script code the host invokes while rendering a failure (a getter on a + * thrown value). `dispose()` waits a bounded grace for the script to settle + * AND its children (stray `agent()` calls included) to finish disposing, + * then ABANDONS whatever is left: pending hook promises are already + * rejected and the script's settlement is contained (no unhandled + * rejection), but an abandoned synchronous spin would still occupy the + * event loop. * * Plugin export shape: a default-exported {@link WorkflowService} subclass * (the class-based service form, like `dsh-bash-local`). @@ -55,7 +63,11 @@ export interface Config { maxItemsPerCall?: number /** vm timeout for the script's initial synchronous slice AND the meta-literal evaluation (default 5000 ms). */ syncTimeoutMs?: number - /** How long `dispose()` waits for a cancelled script to settle before abandoning it (default 5000 ms). */ + /** + * How long after a cancellation an unsettled script may keep running before + * it is abandoned and `result` force-settles `cancelled` (default 5000 ms); + * also bounds `dispose()`. + */ disposeGraceMs?: number } @@ -110,6 +122,7 @@ export class VmWorkflowEngine extends WorkflowService { maxTotalAgents: this.config.maxTotalAgents, maxItemsPerCall: this.config.maxItemsPerCall, syncTimeoutMs: this.config.syncTimeoutMs, + disposeGraceMs: this.config.disposeGraceMs, } const execution = new WorkflowExecution( this.ctx, @@ -149,9 +162,11 @@ export class VmWorkflowEngine extends WorkflowService { }, dispose: (): Promise => { // Idempotent: cancel, then wait min(settle + child quiescence, grace). - // `result` and `quiesce()` never reject, so the race needs no - // rejection handling; a script or child still unsettled past the grace - // is abandoned per the module contract. + // The cancel itself bounds `result` (the execution abandons a script + // still unsettled `disposeGraceMs` later), so this outer race exists + // for CHILD quiescence: a slow-disposing child must not hold dispose + // past the grace. `result` and `quiesce()` never reject, so the race + // needs no rejection handling. disposed ??= (async () => { execution.cancel('workflow disposed') await Promise.race([ diff --git a/packages/workflow/workflow-vm/src/meta.ts b/packages/workflow/workflow-vm/src/meta.ts index bcb891e85e..cfe3e4d381 100644 --- a/packages/workflow/workflow-vm/src/meta.ts +++ b/packages/workflow/workflow-vm/src/meta.ts @@ -20,7 +20,7 @@ import * as vm from 'node:vm' import { WorkflowError } from '@deepseek-ai/dsh-workflow' import type { WorkflowMeta, WorkflowPhase } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering, REALM_THROWN_RENDERER_SOURCE } from './realm.ts' +import { materializeFromRealm, MaterializeError, renderThrown } from './realm.ts' /** The result of {@link extractMeta}: the validated meta and the runnable body. */ export interface ExtractedScript { @@ -171,18 +171,11 @@ export function extractMeta(script: string, evalTimeoutMs: number): ExtractedScr // An EMPTY context: any non-literal reference (a variable, a call) throws // here. The result — data only — is what the contract checks; a getter or // IIFE can still run, which is why the timeout and the materialization - // below are part of the same boundary. A thrown value is pre-rendered by - // the realm-side catch INSIDE the timed window, so a hostile - // stack/message/toString can neither run on the host catch path nor - // outlive the timeout. - evaluated = vm.runInNewContext( - `(() => { try { return (${literal}) } catch (e) { throw (${REALM_THROWN_RENDERER_SOURCE})(e) } })()`, - undefined, - { timeout: evalTimeoutMs }, - ) + // below are part of the same boundary. + evaluated = vm.runInNewContext(`(${literal})`, undefined, { timeout: evalTimeoutMs }) } catch (error: unknown) { throw new WorkflowError( - `meta block failed to evaluate as a pure literal: ${thrownRendering(error) ?? describeThrown(error)}`, + `meta block failed to evaluate as a pure literal: ${renderThrown(error)}`, 'META_INVALID', { cause: error }, ) diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts index c1f1ff7c5c..f5a2665626 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -1,48 +1,34 @@ /** - * Realm-boundary materialization for the vm engine. + * The vm engine's value boundary: copy script-realm values into plain host + * JSON data — loud about everything JSON cannot carry — and render thrown + * script values to failure text. * - * Values produced INSIDE the script realm (the meta literal, hook arguments, - * the script's return value) must become plain host-realm JSON data before the - * host touches them. The repo's `isJsonValue` guard cannot run first: it is - * prototype-strict (any cross-realm object fails it) and it INVOKES getters - * (letting realm code run outside the vm's timed window). So this module walks - * own-property DESCRIPTORS — never invoking accessors — and copies data into - * host containers, rejecting loud everything JSON cannot carry: - * accessor properties, non-plain prototypes, functions, symbols (keys or - * values), bigints, non-finite numbers, `undefined` values, cycles, sparse - * arrays, arrays with non-index own properties, and proxies. Proxies are - * rejected via the trap-free native `util.types.isProxy` check BEFORE any - * other inspection — a descriptor walk over a proxy would otherwise run its - * realm-side traps (`ownKeys`, `getOwnPropertyDescriptor`, `getPrototypeOf`) - * on the host stack, outside the vm's timed window, and a throwing trap would - * escape as a raw realm error instead of a {@link MaterializeError}. The same - * check guards the PROTOTYPE position (an object whose prototype is a proxy). + * TRUST PREMISE (everything in this module hangs on it): workflow scripts are + * MODEL-WRITTEN, the same trust level as the model's existing bash access, so + * this boundary guards against BUGGY scripts, not hostile ones. It rejects + * loud what JSON would silently mangle — functions, symbols, bigints, + * non-finite numbers, nested `undefined`, cycles, sparse arrays, exotic + * prototypes — because accepted-then-ignored is this repo's banned failure + * mode. It does NOT defend against adversarial values: the walk reads + * properties ordinarily (a getter runs, and whatever it returns is what + * crosses), {@link renderThrown} reads `stack`/`message`/`String()` directly, + * and a proxy is walked through its traps. A hostile script gains nothing + * worth defending here — it can already occupy the event loop forever with a + * synchronous spin past the first await (the engine's documented, accepted + * limitation) — so host-side hostile-value containment would be cost without + * a threat model; genuine hardening is an ENGINE SWAP (worker/isolated-vm, + * where the boundary is serialization by construction), not incremental + * defenses here. * - * Host objects are built with `Object.defineProperty` into a fresh `{}` — - * never plain `target[key] =` assignment, which a `"__proto__"` key would turn - * into prototype mutation instead of a data property. - * - * The host→realm direction deliberately does NOT live here: a host object - * handed into the realm would expose host intrinsics through its prototype - * chain, so the engine rebuilds inbound values INSIDE the realm via the - * context's own `JSON.parse` (see the runtime). - * - * {@link REALM_THROWN_RENDERER_SOURCE}, {@link thrownRendering}, and - * {@link describeThrown} are the same discipline for the one place realm - * values reach the host WITHOUT materialization: a thrown value crossing into - * a host catch block. The renderer runs INSIDE the realm's own execution - * window (compiled into the script wrapper), so reading a hostile - * accessor/`toString` there is subject to the vm sync-slice timeout exactly - * like any other script code; the host side only descriptor-reads the - * pre-rendered string, or falls back to {@link describeThrown}, which invokes - * no getter whose function identity is not the host realm's own native stack - * getter. + * The host→realm direction needs no machinery at all: hooks hand the script + * plain host values, host prototypes included — the script is trusted. One + * consequence is documented in the engine README: an error thrown by a hook + * is a HOST error, so an in-script `instanceof Error` check is false; read + * `name`/`code`/`message` instead. * * @module @deepseek-ai/dsh-workflow-vm/realm */ -import { types } from 'node:util' - /** Thrown by {@link materializeFromRealm}; the caller wraps it into the right `WorkflowError` code. */ export class MaterializeError extends Error { constructor(public readonly path: string, public readonly reason: string) { @@ -52,154 +38,63 @@ export class MaterializeError extends Error { } /** - * Realm-SOURCE text (an arrow-function expression) the engine compiles into - * its script wrappers: `throw (RENDERER)(e)` inside a catch around the whole - * body/literal. It renders the thrown value to a string INSIDE the realm's - * own execution window — a hostile `stack`/`message` accessor or `toString` - * invoked here is subject to the vm sync-slice timeout like any other script - * code (and post-await it is the engine's accepted spin limitation, identical - * to a script reading `e.stack` in its own catch). Host `WorkflowError`s - * thrown by hooks pass through unwrapped (duck-checked by name — a realm - * forgery fails the host's `instanceof` and merely renders data-only); - * everything else becomes `{ __wfThrown: }`, whose only consumer is - * {@link thrownRendering}. Every read is individually contained, so the - * renderer itself never throws. - */ -export const REALM_THROWN_RENDERER_SOURCE = `(e) => { - try { if (e && e.name === 'WorkflowError') return e } catch { /* hostile name getter: fall through to rendering */ } - const rendered = (() => { - try { if (e && typeof e.stack === 'string' && e.stack.length > 0) return e.stack } catch { /* hostile stack getter */ } - try { if (e && typeof e.message === 'string') return e.message } catch { /* hostile message getter */ } - try { return String(e) } catch { /* hostile toString/Symbol.toPrimitive */ } - return '[unrenderable thrown value]' - })() - return { __wfThrown: rendered } -}` - -/** - * The pre-rendered failure text carried by a realm-catch wrapper object - * (`{ __wfThrown: string }` from {@link REALM_THROWN_RENDERER_SOURCE}), or - * `undefined` when `error` is not such a wrapper. Descriptor-read and - * proxy-guarded: never invokes user code. - * @param error - the value a host catch received from script execution. - * @returns the realm-rendered string, or `undefined` to fall back to - * {@link describeThrown}. - */ -export function thrownRendering(error: unknown): string | undefined { - if (typeof error !== 'object' || error === null || types.isProxy(error)) return undefined - const value = ownDataProperty(error, '__wfThrown') - return typeof value === 'string' ? value : undefined -} - -/** - * The host realm's own native `stack` getter (modern V8 makes `stack` an own - * ACCESSOR on Errors); `undefined` where it is a data property. Typed through - * a structural view of the descriptor — it is only ever identity-compared or - * `.call`ed on an explicit receiver, never invoked unbound. - */ -const HOST_STACK_GETTER: unknown = (Object.getOwnPropertyDescriptor(new Error(), 'stack') as { get?: unknown } | undefined)?.get - -/** - * Render a thrown value HOST-SIDE without ever throwing and without running - * any code the host does not own: proxies become a fixed label (trap-free - * `isProxy` before any inspection); `stack` is read as an own data descriptor, - * or through its getter ONLY when that getter's function identity is the host - * realm's own native stack getter (an unforgeable check — realm code cannot - * hold that identity, and the host realm's `prepareStackTrace` is the host's - * own trust domain); `message` is an own-data read; anything else - * object-shaped renders as `[object Object]` untouched; only primitives - * (which cannot carry code) reach `String()`. Used for host-thrown errors - * (vm timeouts, `WorkflowError`s) and as the fallback for adversarial values - * that bypassed the realm-side renderer (e.g. a hostile thenable rejection); - * ordinary script failures arrive pre-rendered via {@link thrownRendering}. + * Render a thrown value to failure text without ever throwing: prefer the + * `stack` (host or realm — a realm error's `stack` is a plain string read), + * fall back to `message`, then `String()`. Reading those properties MAY run + * script code (a getter, `toString`) — accepted under the module's trust + * premise; if that code itself throws, a fixed label is returned instead. * @param error - the thrown value, of any shape and any realm. * @returns human-readable text for the failure report; prefers the stack. */ -export function describeThrown(error: unknown): string { - switch (typeof error) { - case 'object': - break - case 'function': - return '[thrown function]' - default: - // Primitives (string/number/boolean/bigint/symbol/undefined): String() - // cannot reach user code on these. - return String(error) +export function renderThrown(error: unknown): string { + try { + const stack = (error as { stack?: unknown } | null | undefined)?.stack + if (typeof stack === 'string' && stack.length > 0) return stack + const message = (error as { message?: unknown } | null | undefined)?.message + if (typeof message === 'string' && message.length > 0) return message + return String(error) + } catch { + // A throwing accessor/toString on the thrown value — rendering must be + // total (drive()'s never-reject contract), so fall back to a fixed label. + return '[unrenderable thrown value]' } - if (error === null) return 'null' - if (types.isProxy(error)) return '[thrown proxy]' - const stack = readStack(error) - if (typeof stack === 'string' && stack.length > 0) return stack - const message = ownDataProperty(error, 'message') - if (typeof message === 'string') return message - return '[object Object]' -} - -/** - * Read `error.stack` without running foreign code: an own DATA descriptor is - * read directly; an accessor is invoked only on function identity with - * {@link HOST_STACK_GETTER} (never a realm or user function). The native - * getter returns `undefined` on a non-Error receiver rather than throwing. - */ -function readStack(error: object): unknown { - const descriptor = Object.getOwnPropertyDescriptor(error, 'stack') - if (descriptor === undefined) return undefined - if ('value' in descriptor) return descriptor.value - if (typeof descriptor.get !== 'function') return undefined - if (descriptor.get !== HOST_STACK_GETTER) return undefined - return descriptor.get.call(error) -} - -/** An own DATA property's value (`undefined` for absent or accessor); never invokes user code on a non-proxy object. */ -function ownDataProperty(value: object, key: string): unknown { - const descriptor = Object.getOwnPropertyDescriptor(value, key) - return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined -} - -/** - * Whether `error` is a FATAL realm-built `WorkflowError` clone — the shape the - * engine's hooks reject with (host errors are translated at the realm boundary - * so the script never holds host prototypes), duck-checked because a realm - * object cannot be an `instanceof` the host class. Proxy-guarded and - * descriptor-read, so a forged object cannot run code here; a script forging - * the shape only kills its own run (self-sabotage). Combinators use this to - * decide re-throw vs per-item `null`. - * @param error - the value a combinator caught from a realm thunk/stage. - * @returns `true` when the error must propagate and kill the script. - */ -export function isFatalWorkflowErrorClone(error: unknown): boolean { - if (typeof error !== 'object' || error === null || types.isProxy(error)) return false - return ownDataProperty(error, 'name') === 'WorkflowError' && ownDataProperty(error, 'fatal') === true } /** * Whether an object's prototype chain is data-shaped: `null`, or a prototype * whose own prototype is `null` (the realm's `Object.prototype` — which we * cannot compare by identity across realms). A `Date`/`Map`/class instance - * has a longer chain and is rejected, as is a proxy sitting in the prototype - * position (checked trap-free BEFORE its own prototype is dereferenced). + * has a longer chain and is rejected. */ function hasPlainPrototype(value: object): boolean { const proto: unknown = Object.getPrototypeOf(value) if (proto === null) return true - if (types.isProxy(proto)) return false return Object.getPrototypeOf(proto) === null } /** * Copy `value` (typically from the vm realm) into plain host JSON data. * Throws {@link MaterializeError} naming the offending path for anything JSON - * cannot carry losslessly. Accessors are detected via descriptors and NEVER - * invoked. `undefined` is accepted only at the ROOT (a script with no - * `return` value) — the caller decides what it means; an `undefined` nested - * INSIDE a container is a violation. + * cannot carry losslessly. Properties are read ordinarily — a getter runs and + * its RESULT is materialized; a read that throws surfaces as a + * {@link MaterializeError} carrying the rendered failure. `undefined` is + * accepted only at the ROOT (a script with no `return` value) — the caller + * decides what it means; an `undefined` nested INSIDE a container is a + * violation. * @param value - the realm value to materialize. * @param root - the path label for the root value (error messages). * @returns the host-realm copy (plain objects/arrays/scalars only). */ export function materializeFromRealm(value: unknown, root = 'value'): unknown { if (value === undefined) return undefined - return materialize(value, root, new Set()) + try { + return materialize(value, root, new Set()) + } catch (error: unknown) { + if (error instanceof MaterializeError) throw error + // A property read ran script code that threw; total-ize it so callers can + // keep the narrow MaterializeError contract. + throw new MaterializeError(root, `reading the value threw: ${renderThrown(error)}`) + } } function materialize(value: unknown, path: string, seen: Set): unknown { @@ -214,20 +109,15 @@ function materialize(value: unknown, path: string, seen: Set): unknown { case 'bigint': throw new MaterializeError(path, 'bigints are not JSON data') case 'function': - throw new MaterializeError(path, 'functions cannot cross the workflow realm boundary') + throw new MaterializeError(path, 'functions cannot cross the workflow value boundary') case 'symbol': - throw new MaterializeError(path, 'symbols cannot cross the workflow realm boundary') + throw new MaterializeError(path, 'symbols cannot cross the workflow value boundary') case 'undefined': throw new MaterializeError(path, 'undefined is not JSON data') case 'object': break } if (value === null) return null - // BEFORE anything else touches the object: every inspection below — - // Array.isArray aside — can trigger a proxy trap, running realm code on the - // host stack (module doc). isProxy is a native internal-slot check (no - // traps, catches revoked proxies, realm-agnostic). - if (types.isProxy(value)) throw new MaterializeError(path, 'proxies cannot cross the workflow realm boundary') const objectValue: object = value if (seen.has(objectValue)) throw new MaterializeError(path, 'circular references are not JSON data') seen.add(objectValue) @@ -242,10 +132,8 @@ function materialize(value: unknown, path: string, seen: Set): unknown { function materializeArray(value: unknown[], path: string, seen: Set): unknown[] { const out: unknown[] = [] for (let index = 0; index < value.length; index++) { - const descriptor = Object.getOwnPropertyDescriptor(value, index) - if (descriptor === undefined) throw new MaterializeError(`${path}[${index}]`, 'sparse arrays are not JSON data') - if (!('value' in descriptor)) throw new MaterializeError(`${path}[${index}]`, 'accessor properties cannot cross the workflow realm boundary') - out.push(materialize(descriptor.value, `${path}[${index}]`, seen)) + if (!(index in value)) throw new MaterializeError(`${path}[${index}]`, 'sparse arrays are not JSON data') + out.push(materialize(value[index], `${path}[${index}]`, seen)) } // Own enumerable props beyond the indices (e.g. `arr.total = 3`) would be // silently dropped by JSON — reject them instead. @@ -256,7 +144,7 @@ function materializeArray(value: unknown[], path: string, seen: Set): un } } if (Object.getOwnPropertySymbols(value).length > 0) { - throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow realm boundary') + throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow value boundary') } return out } @@ -266,20 +154,16 @@ function materializeObject(value: object, path: string, seen: Set): Reco throw new MaterializeError(path, 'only plain objects and arrays are JSON data (exotic prototype)') } if (Object.getOwnPropertySymbols(value).length > 0) { - throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow realm boundary') + throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow value boundary') } const out: Record = {} - for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) { - // Non-enumerable own props never reach JSON output — skip them, matching - // JSON.stringify's contract exactly (documented in the module doc). - if (!descriptor.enumerable) continue - if (!('value' in descriptor)) { - throw new MaterializeError(`${path}.${key}`, 'accessor properties cannot cross the workflow realm boundary') - } + // Object.keys = own enumerable string keys, matching JSON.stringify's + // property selection exactly (non-enumerable props never reach JSON output). + for (const key of Object.keys(value)) { // defineProperty, never assignment: a "__proto__" key must become an OWN // data property of the copy, not a prototype mutation. Object.defineProperty(out, key, { - value: materialize(descriptor.value, `${path}.${key}`, seen), + value: materialize((value as Record)[key], `${path}.${key}`, seen), enumerable: true, writable: true, configurable: true, diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index 955be94a87..7748cb2f2e 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -4,30 +4,27 @@ * concurrency semaphore and caps, cancellation, and the drive loop that turns * a script settlement into a {@link WorkflowResult}. * - * Realm discipline (see also ./realm.ts): values ENTERING the host from the - * script (hook options, schemas, the return value) are materialized via - * descriptor walks; values ENTERING the realm from the host (`args`, agent() - * results) are rebuilt INSIDE the realm through the context's own - * `JSON.parse`, so the script never holds an object whose prototype chain - * reaches host intrinsics. The same rule covers every other value a hook - * hands the script: the promises `agent`/`parallel`/`pipeline` return are - * realm promises (the realm's own `Promise.resolve` over the host promise), - * the arrays the combinators resolve to are realm-built (their ELEMENTS are - * realm values already — only the container needs rebuilding), and a hook - * failure — rejection or synchronous `phase`/`log` throw — crosses as a - * realm-built clone carrying name/code/message/fatal. Realm functions - * (pipeline stages, parallel thunks) are called, not materialized — their - * values stay realm-side. + * Value boundary (the trust premise lives in ./realm.ts): values ENTERING the + * host from the script (hook options, schemas, the return value) are + * materialized by `materializeFromRealm` — a plain walk that rejects loud + * everything JSON cannot carry. Values ENTERING the realm (`args`, `agent()` + * results, hook promises and their failures, combinator arrays) are handed + * over DIRECTLY as host values: the script is model-written and trusted, so + * host prototypes are not a leak. `args` is host-side `structuredClone`d once + * at start so a script scribbling on it cannot mutate the caller's object — + * that is a benign-bug guard, not isolation. Realm functions (pipeline + * stages, parallel thunks) are called, not materialized — their values stay + * realm-side until they cross through a hook or the final return. * * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments, * unsupported options/schemas, tripped caps, seam start failures, - * cancellation) ALWAYS propagate through `parallel`/`pipeline` — they cross - * the realm boundary as fatal clones, recognized structurally — and the - * per-item `null` is reserved for child-run failures and ordinary in-stage - * script errors. Every hook-returned promise gets a no-op rejection consumer - * attached, so a script that drops a promise (fires an `agent()` without - * awaiting it) cannot surface an unhandled rejection when cancellation - * rejects it — the app boot layer exits the process on unhandled rejections. + * cancellation) ALWAYS propagate through `parallel`/`pipeline` — recognized + * by host `instanceof`, which a script cannot forge — and the per-item `null` + * is reserved for child-run failures and ordinary in-stage script errors. + * Every hook-returned promise gets a no-op rejection consumer attached, so a + * script that drops a promise (fires an `agent()` without awaiting it) cannot + * surface an unhandled rejection when cancellation rejects it — the app boot + * layer exits the process on unhandled rejections. * * @module @deepseek-ai/dsh-workflow-vm/runtime */ @@ -39,14 +36,14 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-subagent' import { assertSupportedOutputSchema, OutputSchemaError } from '@deepseek-ai/dsh-tools' import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' -import { WorkflowError } from '@deepseek-ai/dsh-workflow' +import { isFatalWorkflowError, WorkflowError } from '@deepseek-ai/dsh-workflow' import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowMeta, WorkflowResult, } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering, isFatalWorkflowErrorClone, REALM_THROWN_RENDERER_SOURCE } from './realm.ts' +import { materializeFromRealm, MaterializeError, renderThrown } from './realm.ts' /** The per-run knobs the engine resolves from its Config. */ export interface ExecutionLimits { @@ -60,6 +57,8 @@ export interface ExecutionLimits { maxItemsPerCall: number /** vm timeout for the script's initial synchronous slice. */ syncTimeoutMs: number + /** How long after `cancel()` a still-unsettled script is abandoned (result force-settles `cancelled`). */ + disposeGraceMs: number } /** The engine-side observers the execution reports progress through. */ @@ -124,13 +123,24 @@ export class WorkflowExecution { private readonly controller = new AbortController() private currentPhase: string | undefined private readonly context: vm.Context - private readonly realmJsonParse: (text: string) => unknown - private readonly realmArrayFrom: (items: unknown[]) => unknown[] - private readonly realmPromiseResolve: (value: unknown) => Promise - private readonly realmErrorClone: (name: string, code: string | undefined, message: string, fatal: boolean) => unknown private readonly compiled: vm.Script /** Every live `agent()` call promise — awaited or stray — for {@link quiesce}. */ private readonly inFlightAgents = new Set>() + /** Fires {@link abandoned}; assigned by the promise executor at field initialization. */ + private declareAbandoned!: () => void + private abandonTimer: NodeJS.Timeout | undefined + /** + * Rejects `disposeGraceMs` after {@link cancel} if the script has not + * settled by then. `drive()` races the script against it, so `result` + * ALWAYS settles within the grace of a cancellation — even when the script + * is parked on a promise no hook owns (`await new Promise(() => {})`), which + * cancellation cannot reject. Without this, a consumer awaiting `result` + * before disposing (the tool's shape) would hang forever on such a script, + * wedging its caller past any abort. + */ + private readonly abandoned = new Promise((_, reject) => { + this.declareAbandoned = () => { reject(new WorkflowError('workflow script abandoned after the cancellation grace', 'CANCELLED')) } + }) constructor( private readonly ctx: Context, @@ -144,61 +154,34 @@ export class WorkflowExecution { ) { // Compile FIRST: a body syntax error must throw out of the constructor // (the engine maps it to SCRIPT_PARSE) before any realm state exists. - // The body is wrapped in a realm-side catch that pre-renders any thrown - // value to a string (see REALM_THROWN_RENDERER_SOURCE) — rendering happens - // inside the realm's own execution window, never on a host catch path. // lineOffset compensates for the wrapper line, so stack traces carry the // script's own line numbers (the meta statement was blanked, not removed). try { - this.compiled = new vm.Script( - `(async () => { try {\n${body}\n} catch (e) { throw (${REALM_THROWN_RENDERER_SOURCE})(e) } })()`, - { - filename: `workflow:${meta.name}`, - lineOffset: -1, - }, - ) + this.compiled = new vm.Script(`(async () => {\n${body}\n})()`, { + filename: `workflow:${meta.name}`, + lineOffset: -1, + }) } catch (error: unknown) { throw new WorkflowError(`workflow script does not parse: ${String(error)}`, 'SCRIPT_PARSE', { cause: error }) } this.context = vm.createContext({}, { name: `workflow:${meta.name}` }) vm.runInContext(DETERMINISM_PRELUDE, this.context) - // The realm's own JSON.parse — the host→realm rebuild channel. - const realmJson = vm.runInContext('JSON', this.context) as { parse(text: string): unknown } - this.realmJsonParse = (text: string) => realmJson.parse(text) - // The realm's own Array.from / Promise.resolve / an error factory, bound - // NOW so a script reassigning its globals later cannot swap them: - // combinator results must be realm arrays, hook promises realm promises, - // and hook failures realm-built clones. - this.realmArrayFrom = vm.runInContext('Array.from.bind(Array)', this.context) as (items: unknown[]) => unknown[] - this.realmPromiseResolve = vm.runInContext('Promise.resolve.bind(Promise)', this.context) as (value: unknown) => Promise - this.realmErrorClone = vm.runInContext(`(name, code, message, fatal) => { - const error = new Error(message) - error.name = name - if (code !== undefined) error.code = code - error.fatal = fatal - return error - }`, this.context) as (name: string, code: string | undefined, message: string, fatal: boolean) => unknown + // A run that settles without ever being abandoned leaves `abandoned` + // permanently pending or rejecting into the void — consume it so a late + // grace timer cannot surface an unhandled rejection. + void this.contain(this.abandoned) const globals: Record = { - agent: (prompt: unknown, opts?: unknown) => this.realmFacing(this.track(this.agent(prompt, opts))), - parallel: (thunks: unknown) => this.realmFacing(this.parallel(thunks)), - pipeline: (items: unknown, ...stages: unknown[]) => this.realmFacing(this.pipeline(items, stages)), - phase: (title: unknown) => { - try { - this.phase(title) - } catch (error: unknown) { - throw this.toRealmError(error) - } - }, - log: (message: unknown) => { - try { - this.log(message) - } catch (error: unknown) { - throw this.toRealmError(error) - } - }, - args: this.toRealm(args), + agent: (prompt: unknown, opts?: unknown) => this.contain(this.track(this.agent(prompt, opts))), + parallel: (thunks: unknown) => this.contain(this.parallel(thunks)), + pipeline: (items: unknown, ...stages: unknown[]) => this.contain(this.pipeline(items, stages)), + phase: (title: unknown) => { this.phase(title) }, + log: (message: unknown) => { this.log(message) }, + // Host-side clone: a script scribbling on args must not mutate the + // caller's object (a benign-bug guard; args is plain JSON by the seam + // contract, so structuredClone is total here and throws loud otherwise). + args: args === undefined ? undefined : structuredClone(args), } for (const [key, value] of Object.entries(globals)) { // Data properties on the contextified global; frozen shape not required — @@ -226,7 +209,10 @@ export class WorkflowExecution { /** * Cancel the run: children abort (the shared signal), waiting `agent()` * slots reject, and every future hook call throws `CANCELLED` — the script - * dies at its next await. Idempotent; the first reason wins. + * dies at its next await. A script that STILL has not settled after + * `disposeGraceMs` (parked on a promise no hook owns) is abandoned so + * `result` settles regardless (see {@link abandoned}). Idempotent; the + * first reason wins. */ cancel(reason?: string): void { if (this.cancelReason !== undefined) return @@ -234,14 +220,18 @@ export class WorkflowExecution { this.cancelError = new WorkflowError(`workflow run cancelled: ${this.cancelReason}`, 'CANCELLED') this.controller.abort(this.cancelReason) for (const waiter of this.slotWaiters.splice(0)) waiter.reject(this.cancelledError()) + this.abandonTimer = setTimeout(() => { this.declareAbandoned() }, this.limits.disposeGraceMs) + // unref'd: an armed grace timer must never hold the process open. + this.abandonTimer.unref() } /** * Run the script to settlement. Resolves — never rejects — with the run's * {@link WorkflowResult}: the materialized return value on `completed`, the * failure message on `error`, and `cancelled` when the script died of - * cancellation. After settlement, any stray children a script fired without - * awaiting are aborted (their `agent()` wrappers dispose them). + * cancellation (or outlived its post-cancel grace and was abandoned — see + * {@link abandoned}). After settlement, any stray children a script fired + * without awaiting are aborted (their `agent()` wrappers dispose them). */ async drive(): Promise { try { @@ -249,7 +239,9 @@ export class WorkflowExecution { // the script must not execute at all, let alone report `completed`. if (this.isCancelled()) throw this.cancelledError() const scriptPromise = this.compiled.runInContext(this.context, { timeout: this.limits.syncTimeoutMs }) as Promise - const raw: unknown = await this.contain(Promise.resolve(scriptPromise)) + // The race is the result-settles-after-cancel guarantee: a parked + // script loses to the abandon channel once the grace expires. + const raw: unknown = await Promise.race([this.contain(Promise.resolve(scriptPromise)), this.abandoned]) // Cancelled while the body ran: a script that settled without touching // another hook (or without any) must still report `cancelled` — the // holder asked for cancellation and `completed` would be a lie. @@ -258,25 +250,23 @@ export class WorkflowExecution { return { value, stopReason: 'completed', agentsStarted: this.started } } catch (error: unknown) { // Any failure after cancel() reports `cancelled` with the canonical - // reason — the reject path mirrors the resolve path's post-settle - // check, and a hook CANCELLED failure crosses the realm boundary as a - // clone that deliberately fails the host `instanceof`. + // reason — the reject path mirrors the resolve path's post-settle check. if (this.isCancelled()) { return { value: null, stopReason: 'cancelled', error: this.cancelledError().message, agentsStarted: this.started } } - // Ordinary script failures arrive pre-rendered by the realm-side catch - // (thrownRendering); host-thrown errors (a vm timeout, a WorkflowError) - // and adversarial values that bypassed the wrapper (e.g. a hostile - // thenable rejection) render via the total, host-code-only - // describeThrown. Neither path can throw — drive() resolving is the - // `result` never-rejects seam contract. - return { value: null, stopReason: 'error', error: thrownRendering(error) ?? describeThrown(error), agentsStarted: this.started } + // renderThrown is total (host- and realm-thrown values alike), so this + // arm cannot throw — drive() resolving is the `result` never-rejects + // seam contract. + return { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: this.started } } finally { // Reap strays: a script that fired agent() calls without awaiting them // leaves live children behind after settlement — abort them all. (The // per-call wrappers dispose each child; the contain() consumer keeps // their rejections from going unhandled.) if (this.cancelReason === undefined) this.cancel('workflow settled') + // drive() settling means nothing is left to abandon — including the + // timer the self-cancel above just armed. + if (this.abandonTimer !== undefined) clearTimeout(this.abandonTimer) } } @@ -291,37 +281,6 @@ export class WorkflowExecution { return promise } - /** - * Hand a hook's host promise to the script as a REALM promise (the realm's - * own `Promise.resolve` assimilates it) whose failure reason is a - * realm-built clone — the script must never hold host prototypes, and both - * the promise object and a caught rejection would otherwise expose them - * (module doc). The realm promise gets the same no-op rejection consumer as - * {@link contain}, since the script may drop it; the intermediate host - * promises are handled by the assimilation chain itself. - */ - private realmFacing(hostPromise: Promise): Promise { - const translated = hostPromise.catch((error: unknown) => { - throw this.toRealmError(error) - }) - const realmPromise = this.realmPromiseResolve(translated) - realmPromise.catch(() => { /* consumed: a script-dropped realm promise must not surface an unhandled rejection (see contain) */ }) - return realmPromise - } - - /** - * Rebuild a host failure as a realm-built error clone: a `WorkflowError` - * keeps its name/code/message/fatal (the combinators recognize the shape - * via {@link isFatalWorkflowErrorClone}); anything else becomes a generic - * realm `Error` carrying its {@link describeThrown} rendering. - */ - private toRealmError(error: unknown): unknown { - if (error instanceof WorkflowError) { - return this.realmErrorClone('WorkflowError', error.code, error.message, error.fatal) - } - return this.realmErrorClone('Error', undefined, describeThrown(error), false) - } - /** * Register one `agent()` call promise for {@link quiesce} tracking; the * entry drops when the call fully settles (which is AFTER its child's @@ -354,14 +313,6 @@ export class WorkflowExecution { return this.cancelError ?? new WorkflowError('workflow run cancelled', 'CANCELLED') } - /** Rebuild a host value inside the script realm (via the realm's own JSON.parse). */ - private toRealm(value: unknown): unknown { - if (value === undefined) return undefined - if (value === null) return null - if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value - return this.realmJsonParse(JSON.stringify(value)) - } - /** Materialize the script's return value; violations become RESULT_UNSERIALIZABLE. */ private materializeResult(raw: unknown): unknown { try { @@ -453,7 +404,7 @@ export class WorkflowExecution { return null } this.observer.agentEnd({ ...info, outcome: 'completed' }) - return this.toRealm(result.structured) + return result.structured } this.observer.agentEnd({ ...info, outcome: 'completed' }) return outputText(result.output) @@ -532,20 +483,17 @@ export class WorkflowExecution { } return thunk as () => unknown }) - const settled = await Promise.all(thunks.map(async (thunk) => { + return Promise.all(thunks.map(async (thunk) => { try { return await thunk() } catch (error: unknown) { - // Hooks translate host errors at the realm boundary, so a fatal error - // reaches a thunk catch only as a realm clone (a script forging the - // shape merely kills its own run). - if (isFatalWorkflowErrorClone(error)) throw error + // Hook failures are host WorkflowErrors; a fatal one is recognized by + // host `instanceof` — a script-built object can never pass it, so + // fatality cannot be forged (nor accidentally dissolved). + if (isFatalWorkflowError(error)) throw error return null } })) - // The container must be a REALM array (module doc); the elements are - // realm values already. - return this.realmArrayFrom(settled) } /** The `pipeline(items, ...stages)` hook: per-item stage chains, NO cross-stage barrier. */ @@ -563,7 +511,7 @@ export class WorkflowExecution { } return stage as (previous: unknown, item: unknown, index: number) => unknown }) - const settled = await Promise.all(rawItems.map(async (item: unknown, index) => { + return Promise.all(rawItems.map(async (item: unknown, index) => { let value: unknown = item try { for (const stage of stages) { @@ -572,15 +520,12 @@ export class WorkflowExecution { return value } catch (error: unknown) { // An ordinary stage throw drops the ITEM to null and skips its - // remaining stages; a fatal error (a realm clone — see parallel()) - // kills the whole script. - if (isFatalWorkflowErrorClone(error)) throw error + // remaining stages; a fatal host WorkflowError (see parallel()) kills + // the whole script. + if (isFatalWorkflowError(error)) throw error return null } })) - // The container must be a REALM array (module doc); the elements are - // realm values already. - return this.realmArrayFrom(settled) } private assertItemCap(length: number, hook: string): void { diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-vm/tests/meta.spec.ts index a957b0ae05..02daa02940 100644 --- a/packages/workflow/workflow-vm/tests/meta.spec.ts +++ b/packages/workflow/workflow-vm/tests/meta.spec.ts @@ -103,29 +103,19 @@ return 2` }) it('rejects a literal evaluating to non-JSON data (META_INVALID via materialization)', () => { - const error = bad('export const meta = { name: "x", description: "d", phases: [{ get title() { return "t" } }] }') + const error = bad('export const meta = { name: "x", description: "d", whenToUse: () => 1 }') expect(error.code).toBe('META_INVALID') expect(error.message).toContain('JSON data') }) - it('rejects a meta literal containing a proxy as META_INVALID — its traps never run', () => { - // bad() rethrows anything that is not a WorkflowError, so a trap firing - // ('trap ran') would fail this test instead of mapping to META_INVALID. - const error = bad('export const meta = { name: "x", description: "d", phases: new Proxy([], { getPrototypeOf() { throw new Error("trap ran") } }) }') - expect(error.code).toBe('META_INVALID') - expect(error.message).toContain('proxies cannot cross') - }) - - it('a meta expression THROWING a hostile value maps to META_INVALID — rendering stays realm-side', () => { - // bad() rethrows anything that is not a WorkflowError, so a hostile value - // escaping the realm-side renderer raw would fail this test. - const error = bad('export const meta = { name: (() => { throw { get stack() { throw new Error("boom") }, toString() { throw new Error("boom") } } })(), description: "d" }\nreturn 1') + it('a meta expression that THROWS maps to META_INVALID carrying the rendered value', () => { + const error = bad('export const meta = { name: (() => { throw "nope" })(), description: "d" }\nreturn 1') expect(error.code).toBe('META_INVALID') expect(error.message).toContain('pure literal') - expect(error.message).toContain('[unrenderable thrown value]') + expect(error.message).toContain('nope') }) - it('a spinning meta expression (even inside a thrown stack getter) dies by the eval timeout', () => { + it('a spinning meta expression dies by the eval timeout', () => { try { extractMeta('export const meta = { name: (() => { while (true) {} })(), description: "d" }', 50) throw new Error('expected the extraction to time out') diff --git a/packages/workflow/workflow-vm/tests/realm.spec.ts b/packages/workflow/workflow-vm/tests/realm.spec.ts index c1bdeb33d6..769a19aa71 100644 --- a/packages/workflow/workflow-vm/tests/realm.spec.ts +++ b/packages/workflow/workflow-vm/tests/realm.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' import * as vm from 'node:vm' -import { materializeFromRealm, MaterializeError, describeThrown, thrownRendering } from '../src/realm.ts' +import { materializeFromRealm, MaterializeError, renderThrown } from '../src/realm.ts' /** Evaluate an expression inside a fresh vm realm and hand back the raw realm value. */ function inRealm(expression: string): unknown { @@ -35,17 +35,21 @@ describe('materializeFromRealm', () => { expect(rejection(inRealm('{ a: undefined }'))).toContain('value.a') }) - it('never invokes accessors: a counting getter is rejected, not read', () => { + it('invokes getters ordinarily — the getter RESULT is what crosses (trust premise)', () => { const counter = inRealm(` (() => { globalThis.reads = 0 - return { get x() { globalThis.reads += 1; return 1 } } + return { get x() { globalThis.reads += 1; return globalThis.reads } } })() `) - expect(rejection(counter)).toContain('accessor properties cannot cross') - // The getter body never ran — descriptor inspection only. - expect((counter as { x?: unknown }).x).toBe(1) // sanity: reading DOES run it… - expect(rejection(counter)).toContain('accessor') // …but materialization still never did + expect(materializeFromRealm(counter)).toEqual({ x: 1 }) + }) + + it('a getter that THROWS surfaces as a MaterializeError carrying the rendered failure', () => { + const hostile = inRealm("{ get x() { throw new Error('read failed') } }") + const message = rejection(hostile) + expect(message).toContain('reading the value threw') + expect(message).toContain('read failed') }) it('a "__proto__" key becomes an OWN data property of the copy, never a prototype mutation', () => { @@ -81,39 +85,18 @@ describe('materializeFromRealm', () => { expect(materializeFromRealm(inRealm('Object.assign(Object.create(null), { a: 1 })'))).toEqual({ a: 1 }) }) - it('rejects proxies (root, nested, revoked, host-realm) WITHOUT running any trap', () => { - const trapped = inRealm(`new Proxy({ a: 1 }, { - ownKeys() { throw new Error('trap ran') }, - getOwnPropertyDescriptor() { throw new Error('trap ran') }, - getPrototypeOf() { throw new Error('trap ran') }, - })`) - // A trap firing would surface 'trap ran' (a non-MaterializeError) instead. - expect(rejection(trapped)).toContain('proxies cannot cross') - expect(rejection(inRealm('{ nested: new Proxy([], {}) }'))).toContain('value.nested') - const revoked = inRealm('(() => { const r = Proxy.revocable({}, {}); r.revoke(); return r.proxy })()') - expect(rejection(revoked)).toContain('proxies cannot cross') - expect(rejection(new Proxy({}, {}))).toContain('proxies cannot cross') - }) - - it('rejects an object whose PROTOTYPE is a proxy without dereferencing through it', () => { - const value = inRealm(`Object.create(new Proxy({}, { - getPrototypeOf() { throw new Error('trap ran') }, - }))`) - expect(rejection(value)).toContain('exotic prototype') - }) - it('rejects cycles and accepts the same object reused as a sibling (a DAG)', () => { expect(rejection(inRealm('(() => { const o = {}; o.self = o; return o })()'))).toContain('circular') const dag = inRealm('(() => { const leaf = { v: 1 }; return { a: leaf, b: leaf } })()') expect(materializeFromRealm(dag)).toEqual({ a: { v: 1 }, b: { v: 1 } }) }) - it('rejects sparse arrays, accessor elements, and non-index array properties', () => { + it('rejects sparse arrays and non-index array properties; an array getter element materializes its value', () => { expect(rejection(inRealm('[1, , 3]'))).toContain('sparse') - expect(rejection(inRealm('(() => { const a = [1]; Object.defineProperty(a, 0, { get: () => 1 }); return a })()'))) - .toContain('accessor') expect(rejection(inRealm('(() => { const a = [1]; a.total = 3; return a })()'))) .toContain('non-index') + expect(materializeFromRealm(inRealm('(() => { const a = [1]; Object.defineProperty(a, 0, { get: () => 7, enumerable: true }); return a })()'))) + .toEqual([7]) }) it('skips non-enumerable own properties (matching JSON.stringify exactly)', () => { @@ -134,45 +117,29 @@ describe('materializeFromRealm', () => { }) }) -describe('describeThrown (host-side thrown-value rendering)', () => { - it('renders a HOST Error via its identity-verified native stack getter', () => { - const error = new Error('host failure') - const rendered = describeThrown(error) - expect(rendered).toContain('host failure') - expect(rendered).toContain('at ') // a real stack, not just the message - }) - - it('never invokes a REALM error stack getter (identity mismatch) — message renders instead', () => { +describe('renderThrown', () => { + it('prefers the stack, for host and realm errors alike', () => { + const host = renderThrown(new Error('host failure')) + expect(host).toContain('host failure') + expect(host).toContain('at ') // a real stack, not just the message const realmError: unknown = vm.runInNewContext('(() => { try { throw new Error("realm failure") } catch (e) { return e } })()') - expect(describeThrown(realmError)).toBe('realm failure') + expect(renderThrown(realmError)).toContain('realm failure') }) - it('reads a data-property stack directly and falls through a setter-only accessor', () => { - expect(describeThrown({ stack: 'data stack' })).toBe('data stack') - const setterOnly = { message: 'via message' } - Object.defineProperty(setterOnly, 'stack', { set() { /* swallow */ } }) - expect(describeThrown(setterOnly)).toBe('via message') + it('falls back from stack to message to String()', () => { + expect(renderThrown({ stack: 'custom data stack' })).toBe('custom data stack') + const stackless = new Error('stackless failure') + delete stackless.stack + expect(renderThrown(stackless)).toBe('stackless failure') + expect(renderThrown({ code: 42 })).toBe('[object Object]') + expect(renderThrown('plain')).toBe('plain') + expect(renderThrown(42)).toBe('42') + expect(renderThrown(undefined)).toBe('undefined') + expect(renderThrown(null)).toBe('null') }) - it('labels proxies and functions without touching them; primitives stringify', () => { - expect(describeThrown(new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('trap ran') } }))).toBe('[thrown proxy]') - expect(describeThrown(() => 1)).toBe('[thrown function]') - expect(describeThrown('plain')).toBe('plain') - expect(describeThrown(42)).toBe('42') - expect(describeThrown(undefined)).toBe('undefined') - expect(describeThrown(null)).toBe('null') - expect(describeThrown({ code: 42 })).toBe('[object Object]') - }) -}) - -describe('thrownRendering (the realm-catch wrapper reader)', () => { - it('extracts the pre-rendered string from a wrapper and nothing else', () => { - expect(thrownRendering({ __wfThrown: 'rendered text' })).toBe('rendered text') - expect(thrownRendering({ __wfThrown: 42 })).toBeUndefined() - expect(thrownRendering({ other: 'x' })).toBeUndefined() - expect(thrownRendering(new Error('plain'))).toBeUndefined() - expect(thrownRendering('string')).toBeUndefined() - expect(thrownRendering(null)).toBeUndefined() - expect(thrownRendering(new Proxy({ __wfThrown: 'forged' }, { getOwnPropertyDescriptor() { throw new Error('trap ran') } }))).toBeUndefined() + it('is total: a value whose accessors/toString throw renders as a fixed label', () => { + expect(renderThrown({ get stack() { throw new Error('nope') } })).toBe('[unrenderable thrown value]') + expect(renderThrown({ [Symbol.toPrimitive]() { throw new Error('nope') } })).toBe('[unrenderable thrown value]') }) }) diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index d87d571295..e362ed6ef0 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -289,22 +289,13 @@ describe('dsh-workflow-vm', () => { () => agent('fine'), () => 'plain value', () => { throw 'string throw' }, - () => { throw new Proxy({ name: 'WorkflowError', fatal: true }, {}) }, - () => { throw { name: 'WorkflowError', fatal: 'forged-but-not-true' } }, + () => { throw { name: 'WorkflowError', fatal: true, message: 'forged fatal' } }, ]) `)) - // The last three probe the fatal-clone recognition: a non-object, a - // proxy (never inspected), and a shape miss are all ordinary nulls. - expect(result.value).toEqual([null, 'stub reply', 'plain value', null, null, null]) - }) - - it('a script forging a fatal clone kills only its own run (self-sabotage, not a bypass)', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - return await parallel([() => { throw { name: 'WorkflowError', fatal: true, message: 'forged fatal' } }]) - `)) - expect(result.stopReason).toBe('error') - expect(result.error).toContain('forged fatal') + // The last entry probes fatality: it is recognized by host instanceof, + // which a script-built object can never pass — a WorkflowError-SHAPED + // throw is an ordinary null, and real fatality cannot be forged. + expect(result.value).toEqual([null, 'stub reply', 'plain value', null, null]) }) it('FATAL errors propagate through parallel AND pipeline instead of dissolving into null', async () => { @@ -386,11 +377,12 @@ describe('dsh-workflow-vm', () => { expect((await run(ctx, parent, script("return await agent('p', { effort: 'high' })"))).error).toContain('"effort" is deferred') }) - it('rejects options that are not plain JSON data (an accessor smuggled into opts)', async () => { + it('rejects options whose property reads throw (materialization is loud, not silent)', async () => { const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("return await agent('p', { get label() { return 'x' } })")) + const result = await run(ctx, parent, script("return await agent('p', { get label() { throw new Error('read failed') } })")) expect(result.stopReason).toBe('error') expect(result.error).toContain('options must be plain JSON data') + expect(result.error).toContain('read failed') }) it('validates phase() and log() arguments loudly', async () => { @@ -416,7 +408,7 @@ describe('dsh-workflow-vm', () => { }) }) - describe('determinism bans and realm isolation', () => { + describe('determinism bans and the value boundary', () => { it('Date.now, Math.random, and argless new Date throw; parameterized Date stays usable', async () => { const { ctx, parent } = await setup() expect((await run(ctx, parent, script('return Date.now()'))).error).toContain('Date.now() is not available') @@ -426,18 +418,16 @@ describe('dsh-workflow-vm', () => { expect(ok.value).toBe(0) }) - it('args cross into the realm as data: mutating them (or their prototype chain) cannot reach host intrinsics', async () => { + it('args are cloned at start: a script scribbling on them cannot mutate the caller\'s object', async () => { const { ctx, parent } = await setup() const hostArgs = { files: ['a.ts'], nested: { deep: [1, 2] } } const result = await run(ctx, parent, script(` args.files.push('b.ts') - Object.getPrototypeOf(args).polluted = 'realm-only' return { count: args.files.length, deep: args.nested.deep[1] } `), hostArgs) expect(result.value).toEqual({ count: 2, deep: 2 }) - // The host copy is untouched, and the HOST Object.prototype was never reachable. + // The caller's object is untouched (the engine cloned args host-side). expect(hostArgs.files).toEqual(['a.ts']) - expect(({} as Record).polluted).toBeUndefined() }) it('scalar/null args pass through directly; absent args leave the global undefined', async () => { @@ -447,51 +437,24 @@ describe('dsh-workflow-vm', () => { expect((await run(ctx, parent, script('return typeof args'))).value).toBe('undefined') }) - it('hook promises are REALM promises: instanceof holds in-script, host Promise.prototype stays unreachable', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - const p = agent('x') - const par = parallel([() => 'v']) - const pipe = pipeline([1], (n) => n) - Object.getPrototypeOf(p).wfLeakProbe = 'realm-only' - return { - agentIsRealmPromise: p instanceof Promise, - parallelIsRealmPromise: par instanceof Promise, - pipelineIsRealmPromise: pipe instanceof Promise, - value: await p, - } - `)) - expect(result.stopReason).toBe('completed') - expect(result.value).toEqual({ - agentIsRealmPromise: true, - parallelIsRealmPromise: true, - pipelineIsRealmPromise: true, - value: 'stub reply', - }) - expect((Promise.prototype as unknown as Record).wfLeakProbe).toBeUndefined() - delete (Promise.prototype as unknown as Record).wfLeakProbe - }) - - it('hook failures cross the boundary as realm-built WorkflowError clones', async () => { + it('hook failures reach the script as HOST WorkflowErrors: fields readable, in-realm instanceof Error is false', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` try { await agent('p', { bogus: true }) return 'unreachable' } catch (e) { - Object.getPrototypeOf(Object.getPrototypeOf(e)).wfErrLeakProbe = 'realm-only' + // The documented consequence of the trust premise: hook errors are + // host objects, so realm instanceof is false — read the fields. return { isRealmError: e instanceof Error, name: e.name, code: e.code, fatal: e.fatal, message: e.message } } `)) expect(result.stopReason).toBe('completed') - expect(result.value).toMatchObject({ isRealmError: true, name: 'WorkflowError', code: 'UNSUPPORTED_OPTION', fatal: true }) + expect(result.value).toMatchObject({ isRealmError: false, name: 'WorkflowError', code: 'UNSUPPORTED_OPTION', fatal: true }) expect((result.value as { message: string }).message).toContain('"bogus" is not recognized') - // The script mutated its error's prototype CHAIN — host intrinsics untouched. - expect((Object.prototype as unknown as Record).wfErrLeakProbe).toBeUndefined() - expect((Error.prototype as unknown as Record).wfErrLeakProbe).toBeUndefined() }) - it('a non-WorkflowError host failure (a rejecting provider result) crosses as a generic realm clone', async () => { + it('a non-WorkflowError host failure (a rejecting provider result) reaches the script raw', async () => { const ctx = new Context() await ctx.plugin(SubagentService) const provider: SubagentProvider = { @@ -507,68 +470,34 @@ describe('dsh-workflow-vm', () => { ctx.subagents.registerProvider(provider) await ctx.plugin(VmWorkflowEngine, { provider: 'rejecting' }) const result = await run(ctx, fakeParent(), script(` - try { await agent('p'); return 'unreachable' } catch (e) { return { isRealmError: e instanceof Error, name: e.name, message: e.message } } + try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, message: e.message } } `)) - expect(result.value).toMatchObject({ isRealmError: true, name: 'Error' }) + expect(result.value).toMatchObject({ name: 'Error' }) expect((result.value as { message: string }).message).toContain('backend exploded') }) - it('phase()/log() synchronous throws cross as realm clones too', async () => { + it('phase()/log() throw host WorkflowErrors synchronously on misuse', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` try { phase(3) } catch (e) { - if (!(e instanceof Error) || e.name !== 'WorkflowError') throw e + if (e.name !== 'WorkflowError') throw e } try { log(3) } catch (e) { - return { isRealmError: e instanceof Error, name: e.name, message: e.message } + return { name: e.name, message: e.message } } `)) - expect(result.value).toMatchObject({ isRealmError: true, name: 'WorkflowError' }) + expect(result.value).toMatchObject({ name: 'WorkflowError' }) expect((result.value as { message: string }).message).toContain('log() requires') }) - it('parallel/pipeline resolve to REALM arrays: instanceof holds in-script, host intrinsics stay unreachable', async () => { + it('a returned value whose property reads throw fails loud as RESULT_UNSERIALIZABLE', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` - const fromParallel = await parallel([() => agent('a'), () => 'plain']) - const fromPipeline = await pipeline([1], (prev) => prev + 1) - Object.getPrototypeOf(fromParallel).polluted = 'realm-only' - return { - parallelIsRealmArray: fromParallel instanceof Array, - pipelineIsRealmArray: fromPipeline instanceof Array, - values: [fromParallel[1], fromPipeline[0]], - } - `)) - expect(result.stopReason).toBe('completed') - expect(result.value).toEqual({ - parallelIsRealmArray: true, - pipelineIsRealmArray: true, - values: ['plain', 2], - }) - // The script's prototype mutation stayed realm-side: the HOST - // Array.prototype was never reachable through a combinator result. - expect(([] as unknown as Record).polluted).toBeUndefined() - }) - - it('a returned proxy is rejected as RESULT_UNSERIALIZABLE without running its traps', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - return new Proxy({ a: 1 }, { ownKeys() { throw new Error('trap ran') } }) + return { get a() { throw new Error('read failed') } } `)) expect(result.stopReason).toBe('error') expect(result.error).toContain('not plain JSON data') - expect(result.error).toContain('proxies cannot cross') - expect(result.error).not.toContain('trap ran') - }) - - it('agent() options passed as a proxy are rejected loudly, traps never invoked', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - return await agent('p', new Proxy({}, { ownKeys() { throw new Error('trap ran') } })) - `)) - expect(result.stopReason).toBe('error') - expect(result.error).toContain('options must be plain JSON data') - expect(result.error).not.toContain('trap ran') + expect(result.error).toContain('read failed') }) it('a non-JSON return value fails loud as RESULT_UNSERIALIZABLE', async () => { @@ -696,60 +625,6 @@ describe('dsh-workflow-vm', () => { expect(result.error).toBe('[object Object]') }) - it('hostile thrown values render realm-side: result NEVER rejects, no unhandled rejection', async () => { - const unhandled: unknown[] = [] - const onUnhandled = (reason: unknown): void => { unhandled.push(reason) } - process.on('unhandledRejection', onUnhandled) - try { - const { ctx, parent } = await setup() - // Each thrown value runs code (or throws) when rendered — the realm - // wrapper renders it INSIDE script execution, and the host catch only - // ever descriptor-reads the pre-rendered string. - const cases: [string, string][] = [ - ["throw { get stack() { throw new Error('stack getter threw') } }", '[object Object]'], - ["throw { get stack() { throw new Error('x') }, message: 'getter threw, message renders' }", 'getter threw, message renders'], - ["throw { get message() { throw new Error('message getter threw') } }", '[object Object]'], - ["throw { stack: 'custom data stack' }", 'custom data stack'], - ["throw (() => { const o = { message: 'setter-only stack' }; Object.defineProperty(o, 'stack', { set() {} }); return o })()", 'setter-only stack'], - ["throw new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('gopd trap threw') } })", '[object Object]'], - ["throw { [Symbol.toPrimitive]() { throw new Error('toPrimitive threw') } }", '[unrenderable thrown value]'], - ['throw () => 1', '() => 1'], - ['throw null', 'null'], - ] - for (const [body, rendered] of cases) { - const result = await run(ctx, parent, script(body)) - expect(result.stopReason).toBe('error') - expect(result.error).toBe(rendered) - } - // Let any stray rejection reach the process hook before asserting. - await new Promise(resolve => setTimeout(resolve, 20)) - expect(unhandled).toEqual([]) - } finally { - process.off('unhandledRejection', onUnhandled) - } - }) - - it('a synchronous spin hidden in a thrown stack getter dies by the vm timeout, not on the host', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', syncTimeoutMs: 50 } }) - // The realm-side renderer reads e.stack INSIDE the timed sync slice, so - // the spin is killed exactly like a plain `while (true) {}` body. - const result = await run(ctx, parent, script('throw { get stack() { while (true) {} } }')) - expect(result.stopReason).toBe('error') - expect(result.error?.toLowerCase()).toContain('timed out') - }) - - it('a hostile thenable rejection that bypasses the realm wrapper renders host-side, data-only', async () => { - const { ctx, parent } = await setup() - // Returning a thenable makes the host unwrap it AFTER the script - // settled — its rejection value skips the realm catch entirely and hits - // drive()'s catch raw. The proxy must be labelled, its traps never run. - const result = await run(ctx, parent, script(` - return { then(_resolve, reject) { reject(new Proxy({}, { getOwnPropertyDescriptor() { throw new Error('trap ran') } })) } } - `)) - expect(result.stopReason).toBe('error') - expect(result.error).toBe('[thrown proxy]') - }) - it('falls back to the message for an Error whose stack was stripped', async () => { const { ctx, parent } = await setup() const result = await run(ctx, parent, script(` @@ -803,18 +678,43 @@ describe('dsh-workflow-vm', () => { } }) - it('dispose() abandons a stuck script after the grace instead of hanging (result stays pending)', async () => { + it('cancel() force-settles the result of a script parked on a promise no hook owns', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) + const handle = ctx.workflows.start({ + // No hooks involved: an unsettleable await cancellation cannot reject + // — the abandon grace is the only thing that can settle this run. + script: script("await new Promise(() => {})\nreturn 'unreachable'"), + parent, + }) + handle.cancel('user aborted') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('user aborted') + await handle.dispose() + }) + + it('a never-settling returned thenable is abandoned the same way', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) + const handle = ctx.workflows.start({ script: script('return { then() {} }'), parent }) + handle.cancel() + expect((await handle.result).stopReason).toBe('cancelled') + await handle.dispose() + }) + + it('dispose() abandons a stuck script after the grace instead of hanging (result settles cancelled)', async () => { const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) const handle = ctx.workflows.start({ - // No hooks involved: an unsettleable await the engine cannot reject. script: script("await new Promise(() => {})\nreturn 'unreachable'"), parent, }) const before = Date.now() await handle.dispose() expect(Date.now() - before).toBeLessThan(1000) - const settled = await Promise.race([handle.result.then(() => 'settled'), Promise.resolve('pending')]) - expect(settled).toBe('pending') + // The abandon that freed dispose() also settled result — a consumer + // still awaiting it (the tool does, before its disposing finally) is + // released rather than wedged forever. + const result = await handle.result + expect(result.stopReason).toBe('cancelled') }) it('dispose() is idempotent and settles cleanly after a completed run', async () => { diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md index 46efa2f2d0..076f5443ac 100644 --- a/packages/workflow/workflow/README.md +++ b/packages/workflow/workflow/README.md @@ -4,7 +4,7 @@ The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a wor ## Service: `WorkflowService` (abstract) -`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. +`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` settles within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits. diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 5f340e2f93..83b1560563 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -127,8 +127,8 @@ export type WorkflowEventName = * subset (see dsh-tools). * - `AGENT_CAP` / `ITEM_CAP` — the run/agent caps tripped. * - `AGENT_START` — the subagent seam refused to start a child. - * - `RESULT_UNSERIALIZABLE` — a value crossing the realm boundary is not - * plain JSON data. + * - `RESULT_UNSERIALIZABLE` — a value crossing the script/host value boundary + * is not plain JSON data. * - `CANCELLED` — the run was cancelled; pending and future hooks reject * with this (the script-kill mechanism). */ @@ -179,7 +179,10 @@ export function isFatalWorkflowError(error: unknown): boolean { * - {@link start} throws synchronously for a request that cannot begin (an * unparseable script, an invalid meta block). Once it returns a * {@link WorkflowRun}, `result` NEVER rejects — every failure resolves with - * `stopReason: 'error'` (or `'cancelled'`). + * `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, + * `result` SETTLES within the implementation's bounded grace even if the + * script itself never settles (a consumer awaiting `result` must never be + * wedged past a cancellation). * - The `workflow/*` events fire through {@link emitWorkflowEvent} (data * snapshots, per-listener containment); `workflow/end` fires exactly once * per started run, after `result` is settled or as it settles. diff --git a/packages/workflow/workflow/src/types.ts b/packages/workflow/workflow/src/types.ts index 32377ee46b..01e5d08bf0 100644 --- a/packages/workflow/workflow/src/types.ts +++ b/packages/workflow/workflow/src/types.ts @@ -85,7 +85,7 @@ export interface WorkflowResult { stopReason: WorkflowStopReason /** The failure message (present iff `stopReason` is not `completed`). */ error?: string - /** How many `agent()` calls the run started (across its whole lifetime). */ + /** How many `agent()` calls the run accepted (whole lifetime, including calls still queued for a slot when the run was cancelled). */ agentsStarted: number } @@ -93,17 +93,19 @@ export interface WorkflowResult { * The handle the consumer holds while a script executes. The consumer awaits * `result`, may `cancel` mid-flight, and MUST `dispose` on every path. * `result` does NOT reject — a script failure resolves with `stopReason: - * 'error'` — so the consumer maps a non-`completed` reason to an `isError` - * result. `dispose()` cancels, then waits a bounded grace for the script to - * settle before abandoning it (the engine documents the abandonment - * semantics); it never hangs on a stuck script. + * 'error'` — and once the run is cancelled it SETTLES within the engine's + * bounded grace even if the script itself never settles (the engine abandons + * the script and reports `cancelled`), so a consumer awaiting `result` is + * never wedged past a cancellation. `dispose()` = cancel + that bounded + * settle + child quiescence; it never hangs on a stuck script and is safe to + * call on every path (idempotent). */ export interface WorkflowRun { readonly id: WorkflowRunId /** The validated meta block (available before the body runs). */ readonly meta: WorkflowMeta readonly result: Promise - /** Cancel the run: children abort, pending hooks reject, the script dies at its next await. */ + /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is abandoned at the grace). */ cancel(reason?: string): void /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */ dispose(): Promise @@ -149,6 +151,6 @@ export interface WorkflowResultInfo { stopReason: WorkflowStopReason /** The failure message (present iff `stopReason` is not `completed`). */ error?: string - /** How many `agent()` calls the run started. */ + /** How many `agent()` calls the run accepted (see {@link WorkflowResult.agentsStarted}). */ agentsStarted: number } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7877dc9fad..093e982930 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1060,6 +1060,9 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session + '@deepseek-ai/dsh-subagent': + specifier: workspace:^ + version: link:../../subagent/subagent '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt @@ -1069,6 +1072,9 @@ importers: '@deepseek-ai/dsh-workflow': specifier: workspace:^ version: link:../workflow + '@deepseek-ai/dsh-workflow-vm': + specifier: workspace:^ + version: link:../workflow-vm cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) From ed3972a9c6dad73404100e204fcc191957503341 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 00:51:04 +0800 Subject: [PATCH 012/119] workflow: linear meta-prefix scan (the regex backtracked exponentially) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding, measured: the leading-trivia prefix regex (`^\s*(?:comment|comment|\s+)*export …`) partitions a whitespace run ambiguously between its outer `\s*` and the starred `\s+` alternative, so a script that ultimately FAILS the match backtracks exponentially — ~19 ms at 35 leading whitespace characters, ~174 ms at 38, ×2.2 per character; a realistic near-miss (a comment header, blank indented lines, then `const meta` missing its `export`) did not finish in 10 seconds. The regex ran on the HOST stack inside the synchronous `start()`, where no vm timeout applies and no abort can interleave — a benign one-token typo, exactly what SCRIPT_PARSE exists to bounce back to the model, hung the whole process instead of reaching that designed recovery. Replaced with a hand-rolled linear trivia scan (whitespace + `//` and `/* */` comments — the module already scans characters for the literal) followed by an anchored `^export\s+const\s+meta\s*=\s*` on the remainder, whose quantifiers cannot backtrack ambiguously. An unterminated block comment before the statement now gets its own SCRIPT_PARSE message. Regressions: the near-miss shape must reject in under a second (the old regex would trip the suite timeout), plus the unterminated-leading-comment and comment-to-EOF edges. --- packages/workflow/workflow-vm/src/meta.ts | 45 +++++++++++++++++-- .../workflow/workflow-vm/tests/meta.spec.ts | 21 +++++++++ 2 files changed, 62 insertions(+), 4 deletions(-) diff --git a/packages/workflow/workflow-vm/src/meta.ts b/packages/workflow/workflow-vm/src/meta.ts index cfe3e4d381..75958ba6f1 100644 --- a/packages/workflow/workflow-vm/src/meta.ts +++ b/packages/workflow/workflow-vm/src/meta.ts @@ -29,8 +29,6 @@ export interface ExtractedScript { body: string } -const META_PREFIX = /^\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*|\s+)*export\s+const\s+meta\s*=\s*/ - /** * Scan `source` from `start` (an opening `{`) to its matching `}`, aware of * string literals (`'`/`"`/backtick, with escapes) and comments. Returns the @@ -145,6 +143,44 @@ function validateMetaShape(meta: unknown): { meta?: WorkflowMeta; violations: st } } +/** `export const meta =`, anchored AFTER {@link skipLeadingTrivia} — its quantifiers cannot backtrack ambiguously. */ +const META_HEAD = /^export\s+const\s+meta\s*=\s*/ + +/** + * Index just past the leading trivia: whitespace and `//` / `/*`-style + * comments. A hand-rolled character scan, NOT a prefix regex — an + * all-alternation prefix (`\s*(?:comment|\s+)*`) partitions a whitespace run + * ambiguously and backtracks EXPONENTIALLY when the match ultimately fails, + * so a near-miss script (a comment header, then a forgotten `export`) would + * spin the host synchronously inside `start()`, where no vm timeout applies. + * The near-miss must fail fast into `SCRIPT_PARSE` instead — that error is + * the model's retry signal. + */ +function skipLeadingTrivia(source: string): number { + let index = 0 + while (index < source.length) { + const ch = source.charAt(index) + if (/\s/.test(ch)) { + index += 1 + continue + } + if (ch === '/' && source[index + 1] === '/') { + const end = source.indexOf('\n', index) + if (end === -1) return source.length + index = end + 1 + continue + } + if (ch === '/' && source[index + 1] === '*') { + const end = source.indexOf('*/', index + 2) + if (end === -1) throw new WorkflowError('script has an unterminated comment before the meta block', 'SCRIPT_PARSE') + index = end + 2 + continue + } + break + } + return index +} + /** * Extract and validate the leading `export const meta = {...}` statement. * Throws {@link WorkflowError} — `SCRIPT_PARSE` when the statement is missing @@ -155,11 +191,12 @@ function validateMetaShape(meta: unknown): { meta?: WorkflowMeta; violations: st * @returns the validated meta and the line-preservingly blanked body. */ export function extractMeta(script: string, evalTimeoutMs: number): ExtractedScript { - const match = META_PREFIX.exec(script) + const triviaEnd = skipLeadingTrivia(script) + const match = META_HEAD.exec(script.slice(triviaEnd)) if (!match) { throw new WorkflowError('script must begin with `export const meta = {...}` (leading comments allowed)', 'SCRIPT_PARSE') } - const literalStart = match[0].length + const literalStart = triviaEnd + match[0].length if (script[literalStart] !== '{') { throw new WorkflowError('`export const meta =` must be followed by an object literal', 'SCRIPT_PARSE') } diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-vm/tests/meta.spec.ts index 02daa02940..a1c622e3fc 100644 --- a/packages/workflow/workflow-vm/tests/meta.spec.ts +++ b/packages/workflow/workflow-vm/tests/meta.spec.ts @@ -81,6 +81,27 @@ return 2` expect(bad('export const meta = [1]').code).toBe('SCRIPT_PARSE') }) + it('a near-miss prefix (comment header + whitespace, then no `export`) fails FAST as SCRIPT_PARSE', () => { + // Regression: the previous all-alternation prefix regex backtracked + // exponentially on exactly this shape (~×2 per extra whitespace char once + // the match fails), spinning the host synchronously inside start(). The + // linear trivia scan must reject it in effectively zero time. + const nearMiss = `// deep-audit workflow: reviews every route handler\n${' \n'.repeat(40)}/* second header block */\n${' '.repeat(200)}\nconst meta = { name: 'x', description: 'y' }\n` + const started = Date.now() + expect(bad(nearMiss).code).toBe('SCRIPT_PARSE') + expect(Date.now() - started).toBeLessThan(1000) + }) + + it('an unterminated block comment BEFORE the meta statement is SCRIPT_PARSE', () => { + const error = bad('/* never closed\nexport const meta = { name: "x", description: "y" }') + expect(error.code).toBe('SCRIPT_PARSE') + expect(error.message).toContain('unterminated comment') + }) + + it('a line comment running to EOF leaves no meta statement (SCRIPT_PARSE)', () => { + expect(bad('// only a comment, no newline').code).toBe('SCRIPT_PARSE') + }) + it('rejects template interpolation in the meta block as impure (SCRIPT_PARSE)', () => { const error = bad('export const meta = { name: `w-${1}`, description: "d" }\nreturn 1') expect(error.code).toBe('SCRIPT_PARSE') From 8cb5e1554400fd1103ec900cb9531bc339e09266 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 00:53:17 +0800 Subject: [PATCH 013/119] chore: undo the knip.json reformat noise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review nit: the feature commit exploded every single-line array in knip.json to multi-line, burying the one semantic change (the workflow-vm workspace entry) under ~110 lines of mechanical reformat. Restore the file to master's formatting with only that entry added — the diff against master is now the 4 lines that mean something. --- knip.json | 165 ++++++++++++++---------------------------------------- 1 file changed, 41 insertions(+), 124 deletions(-) diff --git a/knip.json b/knip.json index 39fb4c414f..938164d37d 100644 --- a/knip.json +++ b/knip.json @@ -1,11 +1,7 @@ { "$schema": "https://unpkg.com/knip@5/schema.json", - "exclude": [ - "duplicates" - ], - "ignoreWorkspaces": [ - "vendor/*" - ], + "exclude": ["duplicates"], + "ignoreWorkspaces": ["vendor/*"], "workspaces": { ".": { "entry": [ @@ -15,138 +11,59 @@ "examples/acp-agent/tests/**/*.e2e.ts", "examples/acp-agent/tests/**/*.snapshot.ts" ], - "project": [ - "scripts/**/*.ts", - "examples/**/*.ts" - ] + "project": ["scripts/**/*.ts", "examples/**/*.ts"] }, "packages/*/*": { - "entry": [ - "tests/**/*.spec.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] + "entry": ["tests/**/*.spec.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/util/brand": { - "project": [ - "src/**/*.ts" - ], - "ignoreDependencies": [ - "cordis" - ] + "project": ["src/**/*.ts"], + "ignoreDependencies": ["cordis"] }, "packages/llm/llm-deepseek": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/llm/llm-pi-ai": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/web/web-search-exa": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/web/web-search-perplexity": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] - }, - "packages/web/web-search-deepseek": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] - }, - "packages/ui/acp-agent": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] - }, - "packages/ui/stdio-agent": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] - }, - "packages/subagent/subagent-spawn": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] - }, - "packages/subagent/subagent-acp": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts", - "tests/mock-acp-server.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] - }, - "packages/fs/tool-fs": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/workflow/workflow-vm": { - "entry": [ - "tests/**/*.spec.ts", - "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" - ] + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/web/web-search-deepseek": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/ui/acp-agent": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/ui/stdio-agent": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/subagent/subagent-spawn": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/subagent/subagent-acp": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/mock-acp-server.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, + "packages/fs/tool-fs": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] } } } From 2ba4964aba52c99446d32c019e8b3bb7b97278f8 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 00:54:21 +0800 Subject: [PATCH 014/119] docs: regenerate the services catalog for the seam-contract JSDoc --- docs/cordis-catalog/services.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 88559d658f..0c219b51b5 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -233,7 +233,7 @@ Abstract workflow execution service. Subclass, implement start, and load the sub Semantics every implementation must honor: -- start throws synchronously for a request that cannot begin (an unparseable script, an invalid meta block). Once it returns a WorkflowRun, `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`). +- start throws synchronously for a request that cannot begin (an unparseable script, an invalid meta block). Once it returns a WorkflowRun, `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` SETTLES within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). - The `workflow/*` events fire through emitWorkflowEvent (data snapshots, per-listener containment); `workflow/end` fires exactly once per started run, after `result` is settled or as it settles. - `dispose()` reaches quiescence within a bounded grace: it cancels, waits for the script to settle AND its started children to finish disposing, and abandons whatever is left rather than hanging its caller (the engine documents what abandonment leaves behind). @@ -241,7 +241,7 @@ Semantics every implementation must honor: abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Source: [`packages/workflow/workflow/src/index.ts:191`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:194`](../../packages/workflow/workflow/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) From 706691a7dff8262f640683f74dbd68d6b9ccdeeb Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 01:39:01 +0800 Subject: [PATCH 015/119] workflow: re-check cancellation after the slot acquire MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex convergence round 1 on the review-response commits: agent()'s post-acquire window was real and unguarded. `await acquireSlot()` yields at least one microtask tick even when a slot is free (and a queued waiter resumes a tick after its release), so a cancel() landing in that tick let the continuation start a child carrying an ALREADY-aborted signal — the in-code comment claimed the window could not exist. A provider that subscribes only to future abort events (the test stub; the seam does not promise pre-aborted-signal handling) would never settle such a child, leaking it until the dispose grace abandoned the run, and a backend that misses the pre-aborted signal would burn a full model turn after the user cancelled. agent() now re-checks isCancelled() immediately after the acquire (inside the slot-owning try, so the finally still releases), making every post-cancel path reject before subagents.start. New deterministic regression: cancel() in the same synchronous frame as start() lands in the free-slot await tick — the run settles cancelled with ZERO children started (previously: one leaked child and a grace-delayed settle). The raced-release test's comment now states what it actually pins (the queued-waiter rejection path). Also aligns the RFC's auto-concurrency formula with the code (min(16, max(1, availableParallelism() - 2))). --- .../feature/2026-07-05-dynamic-workflows.md | 2 +- packages/workflow/workflow-vm/src/runtime.ts | 10 +++++---- .../workflow-vm/tests/workflow-vm.spec.ts | 22 +++++++++++++++++-- 3 files changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index f39f12f0ed..c7004f5d19 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -30,7 +30,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre **Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. -**Value boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation; getters are read ordinarily and their RESULT crosses (a throwing read fails loud). Values entering the realm (`args`, `agent()` results, hook promises and failures, combinator arrays) are handed over directly as host values — the script is trusted, so host prototypes are not a leak; `args` is host-`structuredClone`d once so a script cannot mutate the caller's object. Hook failures are host `WorkflowError`s: the combinators recognize fatality by host `instanceof` (unforgeable from the realm), and the script-visible consequence — in-script `instanceof Error` is `false` for hook errors; branch on `e.name`/`e.code` — is documented in the engine README. Realm functions (stages, thunks) are called, never materialized. Thrown script values are rendered by a total host-side renderer (stack → message → `String()`, fixed label if rendering throws), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, cores - 2)`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. +**Value boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation; getters are read ordinarily and their RESULT crosses (a throwing read fails loud). Values entering the realm (`args`, `agent()` results, hook promises and failures, combinator arrays) are handed over directly as host values — the script is trusted, so host prototypes are not a leak; `args` is host-`structuredClone`d once so a script cannot mutate the caller's object. Hook failures are host `WorkflowError`s: the combinators recognize fatality by host `instanceof` (unforgeable from the realm), and the script-visible consequence — in-script `instanceof Error` is `false` for hook errors; branch on `e.name`/`e.code` — is documented in the engine README. Realm functions (stages, thunks) are called, never materialized. Thrown script values are rendered by a total host-side renderer (stack → message → `String()`, fixed label if rendering throws), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, max(1, availableParallelism() - 2))`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. ### The consumer (dsh-tool-workflow) diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index 7748cb2f2e..af8a30927e 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -375,10 +375,12 @@ export class WorkflowExecution { await this.acquireSlot() try { - // No cancelled re-check here: a cancel cannot interleave between a - // waiter's resolution and this continuation (single-threaded, no await - // between them), and a child started moments after a cancel still dies - // via the shared abort signal — the CANCELLED mapping below covers it. + // Re-check after the acquire: the await yields at least one microtask + // tick even when a slot is free, and a queued waiter resumes a tick + // after its release — a cancel() landing in either window must not + // start a child (it would carry an ALREADY-aborted signal, which a + // provider subscribing only to future abort events would never see). + if (this.isCancelled()) throw this.cancelledError() let run try { run = this.ctx.subagents.start(this.limits.provider, { diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index e362ed6ef0..7c56d245ae 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -636,6 +636,22 @@ describe('dsh-workflow-vm', () => { expect(result.error).toBe('stackless failure') }) + it('cancel() in the same frame as start(): the awaited slot tick cannot start a child', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + // agent() enters during start()'s synchronous slice and suspends on the + // acquireSlot await (one microtask tick even with a free slot); the + // synchronous cancel below lands in that tick. Without the post-acquire + // re-check the continuation would start a child carrying an ALREADY- + // aborted signal — which the stub provider (subscribing only to future + // abort events, like a real backend) would never settle, leaking it. + const handle = ctx.workflows.start({ script: script("return await agent('never')"), parent }) + handle.cancel('immediately after start') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(provider.runs.length).toBe(0) + await handle.dispose() + }) + it('a waiter resumed by a release RACING a cancel still dies at the post-acquire check', async () => { const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 1 } }) const handle = ctx.workflows.start({ @@ -643,8 +659,10 @@ describe('dsh-workflow-vm', () => { parent, }) await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) - // Same synchronous block: the release resolves b's waiter, then the - // cancel lands BEFORE b's continuation runs — b must not start a child. + // Same synchronous block: b is still a QUEUED waiter when the cancel + // lands, so cancel() rejects it outright; together with the immediate- + // cancel test above (the resumed-waiter tick), no post-cancel path can + // reach subagents.start. provider.runs[0]!.settle(text('a-done')) handle.cancel('raced') const result = await handle.result From 80250a8f2e4fd7c03bcb7ea95f5c2efa929b9c7f Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 01:53:44 +0800 Subject: [PATCH 016/119] workflow: drop the dead abandon-timer guard in drive()'s finally MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The per-file branch gate caught it: drive()'s finally always cancels first, and every first cancel() arms the abandon timer, so the `!== undefined` guard's false arm was unreachable. clearTimeout tolerates undefined by contract — call it unguarded. --- packages/workflow/workflow-vm/src/runtime.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index af8a30927e..b2a117fdcc 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -265,8 +265,9 @@ export class WorkflowExecution { // their rejections from going unhandled.) if (this.cancelReason === undefined) this.cancel('workflow settled') // drive() settling means nothing is left to abandon — including the - // timer the self-cancel above just armed. - if (this.abandonTimer !== undefined) clearTimeout(this.abandonTimer) + // timer the self-cancel above just armed (cancel() always arms it, so + // it is never undefined here; clearTimeout tolerates undefined anyway). + clearTimeout(this.abandonTimer) } } From 510e80e447d1cb1924d080196c2c6a317f56907d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 6 Jul 2026 14:35:24 +0800 Subject: [PATCH 017/119] test: update ACP request-header snapshots --- examples/acp-agent/tests/snapshots/cancel/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/error-finish/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/fs-edit/session.jsonl | 2 +- .../acp-agent/tests/snapshots/fs-policy-reject/session.jsonl | 2 +- .../acp-agent/tests/snapshots/fs-read-window/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/fs-read/session.jsonl | 2 +- .../acp-agent/tests/snapshots/fs-terminal-card/session.jsonl | 2 +- .../tests/snapshots/fs-write-overwrite/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/fs-write/session.jsonl | 2 +- .../tests/snapshots/hook-cc-posttool-block/session.jsonl | 2 +- .../tests/snapshots/hook-cc-posttool-context/session.jsonl | 2 +- .../tests/snapshots/hook-cc-pretool-ask/session.jsonl | 2 +- .../tests/snapshots/hook-cc-pretool-deny/session.jsonl | 2 +- .../snapshots/hook-cc-promptsubmit-context/session.jsonl | 2 +- .../tests/snapshots/hook-cc-stop-continue/session.jsonl | 2 +- .../tests/snapshots/hook-codex-posttool-block/session.jsonl | 2 +- .../tests/snapshots/hook-codex-posttool-context/session.jsonl | 2 +- .../tests/snapshots/hook-codex-pretool-block/session.jsonl | 2 +- .../snapshots/hook-codex-promptsubmit-context/session.jsonl | 2 +- .../tests/snapshots/hook-codex-stop-continue/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/multi-turn/session.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-fork/session.1.jsonl | 4 ++-- .../acp-agent/tests/snapshots/subagent-fork/session.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl | 4 ++-- .../acp-agent/tests/snapshots/subagent-mixed/session.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-multi/session.1.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-multi/session.2.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-multi/session.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl | 2 +- .../acp-agent/tests/snapshots/subagent-spawn/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/text-turn/session.jsonl | 2 +- examples/acp-agent/tests/snapshots/todo-plan/session.jsonl | 2 +- .../acp-agent/tests/snapshots/tool-call-turn/session.jsonl | 2 +- .../acp-agent/tests/snapshots/workspace-edit/session.jsonl | 2 +- 35 files changed, 37 insertions(+), 37 deletions(-) diff --git a/examples/acp-agent/tests/snapshots/cancel/session.jsonl b/examples/acp-agent/tests/snapshots/cancel/session.jsonl index 09649f4b75..58e4ffb8b7 100644 --- a/examples/acp-agent/tests/snapshots/cancel/session.jsonl +++ b/examples/acp-agent/tests/snapshots/cancel/session.jsonl @@ -2,7 +2,7 @@ {"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":"Start a long task; this turn will be cancelled mid-stream."}],"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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"partial"}}} {"type":"step/end","seq":6,"time":0,"data":{"turn":1,"step":1}} diff --git a/examples/acp-agent/tests/snapshots/error-finish/session.jsonl b/examples/acp-agent/tests/snapshots/error-finish/session.jsonl index 3c55987615..6d400a53d1 100644 --- a/examples/acp-agent/tests/snapshots/error-finish/session.jsonl +++ b/examples/acp-agent/tests/snapshots/error-finish/session.jsonl @@ -2,6 +2,6 @@ {"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":"This prompt triggers a recorded provider error."}],"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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"step/end","seq":4,"time":0,"data":{"turn":1,"step":1}} {"type":"turn/end","seq":5,"time":0,"data":{"turn":1,"reason":{"kind":"error","step":1,"message":"simulated provider error (HTTP 401)","code":"AUTH"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl b/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl index 869926f8c2..37bfe01833 100644 --- a/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279365277,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279365278,"data":{"content":[{"type":"text","text":"First use the read tool to read config.txt in the current directory. Then use the edit tool (NOT bash) to replace the literal text DEBUG with RELEASE in that file. Then reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279365279,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279365279,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-0g5rlt.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279365279,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-0g5rlt.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279365884,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279365884,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} {"type":"assistant/chunk","seq":6,"time":1783279365982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl b/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl index 3e329ba6c6..842d0e2777 100644 --- a/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279382954,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279382954,"data":{"content":[{"type":"text","text":"Do NOT use the read tool. Immediately use the edit tool to replace the literal text blue with green in settings.txt in the current directory. Do not read the file first. After the tool result, reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279382955,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279382956,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-qgXmIP.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279382956,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-qgXmIP.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279383606,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279383606,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279383721,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl b/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl index 25fa56433e..9a00ad40ca 100644 --- a/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279377803,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279377804,"data":{"content":[{"type":"text","text":"Use the read tool (NOT bash) with offset 5 and limit 4 to read lines 5 through 8 of big.txt in the current directory. Then reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279377806,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279377806,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-mA31X1.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279377806,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-mA31X1.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279378450,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279378450,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279378533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-read/session.jsonl b/examples/acp-agent/tests/snapshots/fs-read/session.jsonl index 3bcbd1f52d..85fd577e87 100644 --- a/examples/acp-agent/tests/snapshots/fs-read/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-read/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279355670,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279355671,"data":{"content":[{"type":"text","text":"Use the read tool (NOT bash) to read the file greeting.txt in the current directory, then reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279355673,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279355673,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-Zo3aiO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279355673,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-Zo3aiO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279356329,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279356330,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279356465,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl b/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl index a17da232ca..d9fac13ea8 100644 --- a/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279337866,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279337867,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279337868,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279337871,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-ImzwJW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279337871,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-ImzwJW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279338459,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279338459,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279338579,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl b/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl index 2ad67e723a..fdf94ea612 100644 --- a/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl @@ -2,7 +2,7 @@ {"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":"First use the read tool to read data.txt in the current directory. Then use the write tool (NOT bash) to replace its entire contents with exactly the single line: replaced. Then reply with exactly the single word 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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-write/session.jsonl b/examples/acp-agent/tests/snapshots/fs-write/session.jsonl index 002b7c11ca..abef504690 100644 --- a/examples/acp-agent/tests/snapshots/fs-write/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-write/session.jsonl @@ -2,7 +2,7 @@ {"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 write tool (NOT bash) to create a file named notes.txt in the current directory containing exactly the single line: hello world. Then reply with exactly the single word 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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl index d3124be355..4ac44af230 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279438851,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279438852,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279438853,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279438856,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-4FNHMZ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279438856,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-4FNHMZ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279439575,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279439576,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279439723,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl index 1a93b64d6f..b8235b52b5 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279454673,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279454674,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279454675,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279454676,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-l0uhay.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279454676,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-l0uhay.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279455097,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279455097,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279455192,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl index fe3c13554c..fffda139e8 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279433755,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279433756,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279433757,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279433759,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-GbznxQ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279433759,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-GbznxQ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279434229,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279434229,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279434325,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl index d02081687b..a2a735ffdc 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279428483,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279428484,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279428485,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279428488,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YXKW6X.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279428488,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YXKW6X.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279429149,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279429149,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279429278,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl index a5ca0566f4..53f6cbf940 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl @@ -5,7 +5,7 @@ {"type":"user/message","seq":3,"time":1783279424786,"data":{"content":[{"type":"text","text":"What is my favorite color? Reply with just the color and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"context/message","seq":4,"time":1783279424786,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-claude"}},"surfaceOp":"append"} {"type":"step/start","seq":5,"time":1783279424787,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":6,"time":1783279424788,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-jHjRG4.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":6,"time":1783279424788,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-jHjRG4.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":7,"time":1783279425470,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":8,"time":1783279425471,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":9,"time":1783279425619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl index 159496c81d..929409df1e 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279459589,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279459590,"data":{"content":[{"type":"text","text":"Reply with the single word FIRST and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279459591,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279459592,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-y7ZIlD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279459592,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-y7ZIlD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279460023,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279460023,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279460120,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl index 291700b06e..3e50292d5d 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279472951,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279472952,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279472953,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279472957,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-up4xkk.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279472957,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-up4xkk.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279473683,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279473683,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279473835,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl index c1a6985396..dc8e1fe918 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279478902,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279478903,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279478904,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279478905,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-S4Pl3Q.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279478905,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-S4Pl3Q.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279479573,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279479573,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279479735,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl index 5b3c67c3ac..bc84fb16ac 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279467545,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279467546,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279467547,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279467548,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XJzzAW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279467548,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XJzzAW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279468248,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279468248,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279468448,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl index 815e311638..d0dc0b550c 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl @@ -5,7 +5,7 @@ {"type":"user/message","seq":3,"time":1783279463864,"data":{"content":[{"type":"text","text":"What is my favorite color? Reply with just the color and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"context/message","seq":4,"time":1783279463864,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-codex"}},"surfaceOp":"append"} {"type":"step/start","seq":5,"time":1783279463865,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":6,"time":1783279463866,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-dXMGno.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":6,"time":1783279463866,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-dXMGno.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":7,"time":1783279464538,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":8,"time":1783279464539,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":9,"time":1783279464680,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl index 200002f660..bd7f21b30b 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279484315,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279484316,"data":{"content":[{"type":"text","text":"Reply with the single word FIRST and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279484317,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279484319,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-CW2Kzh.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279484319,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-CW2Kzh.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279484964,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279484964,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279485118,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl b/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl index 34b132fc9b..d1488562b9 100644 --- a/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279390951,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279390951,"data":{"content":[{"type":"text","text":"Reply with exactly the word: ONE. No tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279390953,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279390953,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YRz0cJ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279390953,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YRz0cJ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279391532,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279391532,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279391637,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl index 6bd3e572a6..b9df18dad9 100644 --- a/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279408071,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279408071,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is MARMALADE. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279408072,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279408906,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} @@ -35,7 +35,7 @@ {"type":"turn/start","seq":33,"time":1783279410879,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":34,"time":1783279410880,"data":{"content":[{"type":"text","text":"What is the project codeword mentioned earlier in this conversation? Reply with exactly that one word and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":35,"time":1783279410880,"data":{"turn":2,"step":1}} -{"type":"request/header","seq":36,"time":1783279410880,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} +{"type":"request/header","seq":36,"time":1783279410880,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} {"type":"assistant/chunk","seq":37,"time":1783279411585,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":38,"time":1783279411586,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":39,"time":1783279411711,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl index 0c2ae83d17..e21dba852b 100644 --- a/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279408071,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279408071,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is MARMALADE. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279408072,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279408906,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl index 0a9360546a..7f426c7e0f 100644 --- a/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279418198,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279418198,"data":{"content":[{"type":"text","text":"Reply with exactly the word ALPHA and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279418198,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279418198,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279418198,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279418756,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279418756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279418937,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl index 449acfb168..eec185bfd7 100644 --- a/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279415444,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279415445,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is SAFFRON. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279415446,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279416310,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} @@ -29,7 +29,7 @@ {"type":"turn/start","seq":27,"time":1783279420404,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":28,"time":1783279420404,"data":{"content":[{"type":"text","text":"What is the project codeword mentioned earlier in this conversation? Reply with exactly that one word and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":29,"time":1783279420405,"data":{"turn":2,"step":1}} -{"type":"request/header","seq":30,"time":1783279420405,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} +{"type":"request/header","seq":30,"time":1783279420405,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} {"type":"assistant/chunk","seq":31,"time":1783279421097,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":32,"time":1783279421098,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":33,"time":1783279421204,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl index c8ace8254e..9d6fe663cd 100644 --- a/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279415444,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279415445,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is SAFFRON. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279415446,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279416310,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl index b40d4f9845..d650e3f381 100644 --- a/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279402204,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279402204,"data":{"content":[{"type":"text","text":"Reply with exactly the word ALPHA and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279402205,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279402205,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279402205,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279402608,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279402608,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279402723,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl index a49d90b80f..6e37fa2ad6 100644 --- a/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279403730,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279403730,"data":{"content":[{"type":"text","text":"Reply with exactly the word BETA and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279403730,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279403730,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279403730,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279404370,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279404370,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279404532,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl index 7c1cf16d55..0960b62547 100644 --- a/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279400642,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279400642,"data":{"content":[{"type":"text","text":"Use the subagent tool TWICE, once at a time, to delegate two subtasks to child agents. First subtask: 'Reply with exactly the word ALPHA and nothing else.' Second subtask (after the first returns): 'Reply with exactly the word BETA and nothing else.' After both subagents return, reply with the single word PARENT_DONE and stop. Do not use the bash tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279400643,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279400646,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279400646,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279401312,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279401312,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279401437,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl index abd72a7ab5..c38e6d2988 100644 --- a/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279396597,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279396597,"data":{"content":[{"type":"text","text":"Reply with exactly the word CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279396598,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279396598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279396598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279397154,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279397154,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279397252,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl index edb2f9be7a..f0bc7d96f2 100644 --- a/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279395301,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279395302,"data":{"content":[{"type":"text","text":"Use the subagent tool exactly once to delegate this subtask to a child agent: 'Reply with exactly the word CHILD_OK and nothing else.' After the subagent returns, reply with the single word PARENT_DONE and stop. Do not use the bash tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279395303,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279395304,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279395304,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279395862,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279395862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279395973,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index afdd312983..539747bd0c 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279329596,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279329596,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279329598,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279330154,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl b/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl index 54fc71daaa..5e4e8db328 100644 --- a/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl +++ b/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279342895,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279342896,"data":{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279342897,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279342898,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-t9J1QD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279342898,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-t9J1QD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279343592,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279343592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279343701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl b/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl index e0bd20f7c7..ebb703ee55 100644 --- a/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279332863,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279332864,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo SNAPSHOT_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279332865,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279332868,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-lH9qMe.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279332868,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-lH9qMe.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279333505,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279333505,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279333653,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl index 5c250d00fb..e9b19b4fda 100644 --- a/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl +++ b/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl @@ -2,7 +2,7 @@ {"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":"A file named greeting.txt in the current directory contains one word. Use the bash tool to append a second line containing the word WORLD to it (so it has two lines), then read the file back with `cat greeting.txt` to confirm, and reply with the single word DONE. Use a single bash call per action."}],"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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} From 8615e019d349b5527f10569d913d8ff6d7f1bcd9 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Mon, 6 Jul 2026 16:23:52 +0800 Subject: [PATCH 018/119] feat(timeout): add dsh-timeout and converge bash + web_fetch onto it Timeout timing/classification was re-implemented three ways across the tool-bearing capabilities, with the fusion of timeout+cancel and the timeout-vs-cancel reason recovery being the error-prone parts. Extract that shared half into a zero-dependency @deepseek-ai/dsh-timeout library (clampTimeout/deadline/timeoutOf/TimeoutReason) and leave the non-shareable hard-kill in each capability, per the timeout-library RFC. bash: run() owns the deadline; runBash drops its killTimer and no longer classifies (SpawnSpec/SpawnOutcome lose timeoutMs/timedOut/aborted), so the public timedOut/aborted booleans become mutually-exclusive first-abort classifications. web_fetch: the hand-rolled controller/timer/listener/ signal.reason dance is replaced by provider-owned deadline/timeoutOf, keeping the WEB_FETCH_TIMEOUT / WEB_ABORTED contract. fs stays timeout-free (README states why). --- docs/module-graph.md | 8 +- docs/rfc/INDEX.md | 1 + .../2026-07-06-timeout-deadline-library.md | 98 +++++++++++ knip.json | 5 + packages/bash/bash-local/package.json | 2 + packages/bash/bash-local/src/index.ts | 36 ++-- packages/bash/bash-local/src/run.ts | 48 +++--- .../bash/bash-local/tests/executor.spec.ts | 16 ++ packages/bash/bash-local/tests/run.spec.ts | 25 ++- packages/bash/bash-local/tsconfig.json | 3 + packages/fs/README.md | 5 + packages/util/README.md | 3 + packages/util/timeout/README.md | 40 +++++ packages/util/timeout/package.json | 30 ++++ packages/util/timeout/src/index.ts | 149 ++++++++++++++++ packages/util/timeout/tests/timeout.spec.ts | 160 ++++++++++++++++++ packages/util/timeout/tsconfig.json | 11 ++ packages/web/web-fetch-local/package.json | 2 + packages/web/web-fetch-local/src/provider.ts | 70 +++----- packages/web/web-fetch-local/tsconfig.json | 3 + pnpm-lock.yaml | 12 ++ tsconfig.build.json | 1 + tsconfig.json | 1 + 23 files changed, 638 insertions(+), 91 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md create mode 100644 packages/util/timeout/README.md create mode 100644 packages/util/timeout/package.json create mode 100644 packages/util/timeout/src/index.ts create mode 100644 packages/util/timeout/tests/timeout.spec.ts create mode 100644 packages/util/timeout/tsconfig.json diff --git a/docs/module-graph.md b/docs/module-graph.md index ed1cc592d4..a4e729484d 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -9,6 +9,7 @@ Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, deri flowchart TD subgraph group_util["packages/util"] pkg_brand["brand"] + pkg_timeout["timeout"] end subgraph group_llm["packages/llm"] pkg_llm["llm"] @@ -86,6 +87,7 @@ flowchart TD pkg_session --> pkg_llm pkg_system_prompt --> pkg_llm pkg_bash_local --> pkg_bash + pkg_bash_local --> pkg_timeout pkg_fs --> pkg_brand pkg_fs --> pkg_llm pkg_web --> pkg_llm @@ -97,6 +99,7 @@ flowchart TD pkg_fs_policy --> pkg_fs pkg_compact --> pkg_llm pkg_compact --> pkg_session + pkg_web_fetch_local --> pkg_timeout pkg_web_fetch_local --> pkg_web pkg_web_search_deepseek --> pkg_web pkg_web_search_exa --> pkg_web @@ -205,6 +208,7 @@ flowchart TD | Package | Group | Depends on | | --- | --- | --- | | [`brand`](../packages/util/brand) | `util` | — | +| [`timeout`](../packages/util/timeout) | `util` | — | | [`app-boot`](../packages/ui/app-boot) | `ui` | — | | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) | | [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand) | @@ -212,14 +216,14 @@ flowchart TD | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) | | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`system-prompt`](../packages/core/system-prompt) | `core` | [`llm`](../packages/llm/llm) | -| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash) | +| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`timeout`](../packages/util/timeout) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) | | [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) | | [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs) | | [`compact`](../packages/compact/compact) | `compact` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`web`](../packages/web/web) | +| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`web`](../packages/web/web) | | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`web`](../packages/web/web) | | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`web`](../packages/web/web) | diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 0c5a11a4f9..5307c381c8 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -118,6 +118,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Add direct directory listing to the filesystem seam](implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md) | 2026-07-03 | | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 | | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 | +| [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 | ### Process diff --git a/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md b/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md new file mode 100644 index 0000000000..84fc5b3ea2 --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md @@ -0,0 +1,98 @@ +# RFC: A shared timeout/deadline primitive, with hard-kill left to each capability + +Status: implemented + +## Problem + +Timeout handling was drifting apart across the tool-bearing capabilities, and the divergence was not superficial — it was the same logic re-implemented three ways, each with its own subtle correctness burden. + +- **bash** ([packages/bash/bash-local/src/run.ts](../../../../packages/bash/bash-local/src/run.ts)) had a full, correct timeout inside the process plumbing: a config-clamped `timeoutMs`, two independent triggers — a `killTimer` for the timeout and an `onAbort` listener for upstream cancellation — each calling one `kill()` closure that escalates SIGTERM→grace→SIGKILL on the process group, and two orthogonal outcome booleans (`timedOut`, `aborted`) latched independently. +- **web_fetch** ([packages/web/web-fetch-local/src/provider.ts](../../../../packages/web/web-fetch-local/src/provider.ts)) had a correct but *hand-rolled* timeout: it constructed an `AbortController`, wired `setTimeout(() => controller.abort(new WebError(…, 'WEB_FETCH_TIMEOUT')))`, manually added and removed the upstream-signal listener, cleared the timer in a `finally`, and recovered the timeout reason from `signal.reason` in a `translateAbortOrNetwork` helper because the reader surfaces a bare `AbortError`. +- **web_search** ([packages/web/tool-web/src/search.ts](../../../../packages/web/tool-web/src/search.ts)) had **no timeout at all**: `WebSearchRequest` ([packages/web/web/src/types.ts](../../../../packages/web/web/src/types.ts)) carries no `timeoutMs` field, and each provider's `search()` only forwards `exec.signal`. (web_search stays untimed here — see Consequences.) + +Each new external-process or network tool re-derived the same four things — clamp the requested value, start a timer, fuse the timeout with upstream cancellation, and distinguish "timed out" from "cancelled" on the way out — and the fusion and reason-recovery are exactly the parts that are easy to get subtly wrong (web_fetch's `signal.reason` dance is evidence). At the same time, the *termination* each performs is irreducibly different: bash kills an OS process group (work runs in a child process, outside this runtime, reachable only by signal), while web aborts an in-process `fetch` (undici tears down the socket). There is no single mechanism that can stop all of them. + +The two reference agents surveyed converged on the same split. Codex models "what will end this exec early" as one value (`ExecExpiration`, an enum fusing timeout and a cancellation token) whose `wait_with_outcome()` returns `TimedOut | Cancelled`, while the actual `kill_process_group` lives outside it — and that abstraction is reused *only* across the exec family, with MCP, model-stream, and guardian each keeping their own bespoke `tokio::time::timeout`. Claude Code shares nothing: bash and ripgrep each own a private SIGTERM→SIGKILL kill and distinguish timeout from cancellation by throwing distinct error types, while file I/O has no timeout. Both confirm the boundary drawn here: the timing-and-classification half is worth sharing within a family of like-terminated operations; the termination half is not shareable and stays in each capability. + +## Decision + +`@deepseek-ai/dsh-timeout` lives under `packages/util/` (peer to `dsh-brand`) and owns the *timing and classification* half of timeout; the *termination* half — the hard kill — stays in each capability's implementation. It is a library of pure functions, **not** a cordis service or plugin: it takes no `ctx`, registers nothing, holds no cross-call state, and emits no events. There is deliberately no central "timeout service" that would have to know how to stop every capability's work — that knowledge is exactly what a microkernel keeps out of shared layers, and what Codex's exec-only `ExecExpiration` scope demonstrates. + +### The library surface + +Three functions plus one reason type: + +```ts ignore-check +/** The internal reason attached to a timeout abort, so consumers can classify it after the fact. */ +export class TimeoutReason extends Error { + override name = 'TimeoutReason' + + constructor(readonly code: string, readonly timeoutMs: number) { + super(`${code} after ${timeoutMs}ms`) + } +} + +/** Validate/fill a caller's optional positive hint from the backend's default, then cap at its max. */ +export function clampTimeout( + requested: number | undefined, + def: number, + max: number, + name = 'timeoutMs', +): number + +/** + * Build a deadline signal that aborts on upstream cancellation OR on timeout, + * with the timeout carrying a `TimeoutReason`. `timeoutMs <= 0` means "no + * timeout" (background tasks): forward only the upstream signal, arm no timer. + * The returned object's `[Symbol.dispose]` clears the timer — `using` for a + * scope-lifetime consumer, a manual call for an event-lifetime one. + */ +export function deadline( + upstream: AbortSignal | undefined, + timeoutMs: number, + code: string, +): { signal: AbortSignal; [Symbol.dispose](): void } + +/** Recover the TimeoutReason from an aborted signal (or error), else undefined. */ +export function timeoutOf(x: AbortSignal | { reason?: unknown }): TimeoutReason | undefined +``` + +`deadline` is `AbortSignal.any([upstream, ])` with three things the standard library does not give: a typed, identifiable `TimeoutReason` on the timeout abort (native `AbortSignal.timeout()` yields a fixed `TimeoutError`, indistinguishable across timeout kinds), an internal `timeoutMs <= 0` "no timeout" sentinel for backend-owned background work, and a `Symbol.dispose` cleanup that works with both `using` and manual disposal. `AbortSignal.any` is a Node ≥ 20 primitive; it is the single mechanism that fuses two abort sources into one, adopting the reason of whichever fires first. External request hints validate as positive finite numbers via `clampTimeout` before they reach `deadline`; `0` is not a model-/plugin-facing "disable timeout" value. When `timeoutMs <= 0` and no upstream signal is present, `deadline()` returns a never-aborting signal plus a no-op disposer so callers keep one call shape. `TimeoutReason` is an internal classification reason: providers translate it into seam-specific public errors or result fields before returning to callers. + +### The division of labor + +| Concern | Owner | +|---|---| +| Validate request hint and clamp default/max | `dsh-timeout` (`clampTimeout`) — pure arithmetic plus the shared positive-finite request contract | +| Arm timer, abort on deadline, carry reason, fuse with upstream cancel | `dsh-timeout` (`deadline`) | +| Clear the timer | `dsh-timeout` (`[Symbol.dispose]`) | +| Classify the first abort reason after abort | `dsh-timeout` (`timeoutOf`) | +| **Actually terminate the work** | the capability's implementation | +| The default/max *values* | the capability's config | +| The timeout `code` string | the capability (`WEB_FETCH_TIMEOUT` ≠ `BASH_TIMEOUT`) | + +The signal only *notifies*; termination is always the listener's job, and the listener differs by capability. bash writes its own `addEventListener('abort', kill)` because the OS process lives outside this runtime and nothing else will kill it; web hands `d.signal` to `fetch` and undici tears down the socket. This is why file read/write/edit take **no** `timeoutMs`: a local syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. Both reference agents leave file I/O untimed for the same reason. + +### How each capability consumes it + +- **web_fetch** — the tool stays validate-and-forward; the provider's hand-rolled controller + `setTimeout` + manual listener + `finally` + `signal.reason` recovery is replaced by provider-owned `deadline`/`timeoutOf`. A pre-aborted upstream signal still throws `WEB_ABORTED` up front; otherwise `fetch` runs against the fused `d.signal`, and `translateAbortOrNetwork` classifies a thrown error by the signal (`timeoutOf` → `WEB_FETCH_TIMEOUT`, else aborted → `WEB_ABORTED`, else network → `WEB_PROVIDER_ERROR`). The public error-code contract is unchanged, and `TimeoutReason` never crosses the web seam as the public error. +- **bash** — `resolve()` stays a pure request-to-spec step: it clamps with `clampTimeout(request.timeoutMs, config.timeoutMs, config.maxTimeoutMs, 'bash-local: request.timeoutMs')` and carries `request.signal` through unchanged. Foreground `run()` owns the timeout: `using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')`, then `runBash` receives only `d.signal`. `runBash` no longer owns any timer — it listens for abort and runs its existing SIGTERM→grace→SIGKILL process-group kill, and its `SpawnSpec`/`SpawnOutcome` no longer carry `timeoutMs`/`timedOut`/`aborted` (the executor classifies from the deadline signal instead). `run()` computes `timedOut = timeoutOf(d.signal) !== undefined` and `aborted = d.signal.aborted && !timedOut`, so the public seam booleans (`BashRunResult.timedOut`/`aborted`) are mutually exclusive — the shared deadline reports the cause that first cut the command short. Background `start()` creates no deadline and forwards only the upstream signal, so background tasks stay timeout-free; a task's killed-vs-completed status reads its own `spec.signal.aborted`. + +## Consequences + +- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the seam type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched. +- `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate. +- web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`. +- `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met). + +Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; future ripgrep-backed fs discovery tools can consume the same provider-owned deadline shape once they exist; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job. + +## Alternatives considered + +**A unified timeout *plugin* / `ctx.timeout` service.** Rejected on microkernel grounds. A service that could stop any tool's work would have to understand every capability's termination mechanism (process-group SIGKILL, socket teardown, syscall-boundary checks) — the "kernel knows too much" the architecture forbids. Codex's `ExecExpiration` is scoped to the exec family precisely because the kill it drives (`killpg`) is process-family-specific; MCP and model-stream keep their own. There is no coherent middle layer that owns termination for everything, so the shared piece can only be the pure timing/classification half — a library, not a service. + +**Per-tool ad-hoc timeout, no shared code (the prior status quo, and Claude Code's choice).** Rejected because it was already producing divergence and duplicated correctness burden: web_fetch hand-rolled the exact controller/reason logic that future network/process-backed tools would each have to re-derive, and the fusion + `signal.reason` recovery are the error-prone parts. Claude Code tolerates full duplication; this repo has a single shared abort channel (`exec.signal` on every `execute`) that makes a small shared primitive strictly cleaner, so the cost/benefit differs. + +**A `withTimeout(promise, ms)` wrapper instead of a signal factory.** Rejected because racing a promise against a timer resolves the *tool-call* promise on deadline without stopping the underlying work — the child process or fetch socket leaks on. Handing out a signal and requiring the capability to listen is what forces a real termination path to exist. This mirrors the "dispose must reach quiescence, not just request it" defensive rule. + +**Keep bash's two independent triggers (`killTimer` + `onAbort`) rather than fusing.** Rejected for the convergence goal: fusing into one `deadline` signal removes bash's bespoke timer and gives every capability one shape. The trade-off is that bash's `timedOut`/`aborted` booleans become first-abort classifications rather than independent facts that can both be true when timeout and user abort race before process close. That is acceptable because the result reports the cause that first cut the command short; the termination action stays the same uniform SIGTERM→grace→SIGKILL kill. Note the deliberate non-alignment with Codex: Codex forks its kill by outcome (timeout → immediate SIGKILL; cancel → SIGTERM + 50 ms grace → SIGKILL), whereas the fused signal drives one uniform `kill()` for both, matching Claude Code's unified bash kill. Splitting the kill by `timeoutOf` is possible later if a need appears; there is none now. diff --git a/knip.json b/knip.json index 5e61645458..2e3e101ae1 100644 --- a/knip.json +++ b/knip.json @@ -21,6 +21,11 @@ "project": ["src/**/*.ts"], "ignoreDependencies": ["cordis"] }, + "packages/util/timeout": { + "entry": ["tests/**/*.spec.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"], + "ignoreDependencies": ["cordis"] + }, "packages/llm/llm-deepseek": { "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] diff --git a/packages/bash/bash-local/package.json b/packages/bash/bash-local/package.json index bc1dc7eb40..e3c7ffe33b 100644 --- a/packages/bash/bash-local/package.json +++ b/packages/bash/bash-local/package.json @@ -23,6 +23,7 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-bash": "^0.0.1", + "@deepseek-ai/dsh-timeout": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "dependencies": { @@ -30,6 +31,7 @@ }, "devDependencies": { "@deepseek-ai/dsh-bash": "workspace:^", + "@deepseek-ai/dsh-timeout": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts index cdac3985b8..674f410b50 100644 --- a/packages/bash/bash-local/src/index.ts +++ b/packages/bash/bash-local/src/index.ts @@ -18,6 +18,7 @@ import { Context } from 'cordis' import z from 'schemastery' import { BashExecutor, BashTaskId } from '@deepseek-ai/dsh-bash' import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash' +import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { DEFAULT_GRACE_MS, runBash } from './run.ts' import type { RunInternals, RunningBash } from './run.ts' @@ -114,8 +115,12 @@ export class LocalBashExecutor extends BashExecutor { * values and never re-default. */ resolve(request: BashExecRequest): BashExecSpec { - if (request.timeoutMs !== undefined) assertPositiveFinite('request.timeoutMs', request.timeoutMs) - const timeoutMs = Math.min(request.timeoutMs ?? this.config.timeoutMs, this.config.maxTimeoutMs) + const timeoutMs = clampTimeout( + request.timeoutMs, + this.config.timeoutMs, + this.config.maxTimeoutMs, + 'bash-local: request.timeoutMs', + ) return { command: request.command, workdir: request.workdir ?? this.config.cwd ?? process.cwd(), @@ -132,29 +137,38 @@ export class LocalBashExecutor extends BashExecutor { } async run(spec: BashExecSpec): Promise { + // One fused deadline drives both the timeout and upstream cancellation; + // runBash listens on d.signal and runs the SIGTERM→grace→SIGKILL kill. + // `using` clears the timer across the awaited process lifetime. + using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT') const outcome = await runBash({ command: spec.command, cwd: spec.workdir, - timeoutMs: spec.timeoutMs, maxOutputBytes: this.config.maxOutputBytes, graceMs: this.config.graceMs, - signal: spec.signal, + signal: d.signal, stdin: spec.stdin, env: spec.env, }, this.internals).done - return { ...outcome, timeoutMs: spec.timeoutMs } + // Classify the FIRST abort reason: a TimeoutReason means the timeout cut the + // command short; any other abort is upstream cancellation. Mutually + // exclusive by construction — the fused signal reports one cause, not two + // independently-latched facts. + const timedOut = timeoutOf(d.signal) !== undefined + const aborted = d.signal.aborted && !timedOut + return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs } } start(spec: BashExecSpec): BashTask { // No timeout for background tasks (matches Claude Code, which detaches // the timeout when backgrounding); callers stop tasks via kill() — or // via spec.signal, which the seam contract honors for background runs - // too (runBash wires it to the group kill). spec.timeoutMs is ignored - // here by design. + // too (runBash wires it to the group kill). No deadline is created here, + // so spec.timeoutMs is ignored by design — background tasks stay + // timeout-free (see the timeout-library RFC). const running = runBash({ command: spec.command, cwd: spec.workdir, - timeoutMs: 0, maxOutputBytes: this.config.maxOutputBytes, graceMs: this.config.graceMs, signal: spec.signal, @@ -174,8 +188,10 @@ export class LocalBashExecutor extends BashExecutor { stdoutOffset: 0, stderrOffset: 0, done: running.done.then((outcome) => { - // Abort-killed tasks report as killed, not completed. - if (task.status === 'running') task.status = outcome.aborted ? 'killed' : 'completed' + // Abort-killed tasks report as killed, not completed. Background runs + // forward only the upstream signal (no timeout), so its aborted state + // is the authoritative "was this cancelled" signal. + if (task.status === 'running') task.status = spec.signal?.aborted === true ? 'killed' : 'completed' task.exitCode = outcome.exitCode task.signal = outcome.signal this.notifyTaskDone(task) diff --git a/packages/bash/bash-local/src/run.ts b/packages/bash/bash-local/src/run.ts index 489d380787..98ccca19e7 100644 --- a/packages/bash/bash-local/src/run.ts +++ b/packages/bash/bash-local/src/run.ts @@ -6,6 +6,12 @@ * Everything here is deliberately free of Cordis concepts so it can be unit * tested in isolation; `LocalBashExecutor` owns lifecycle and configuration. * + * runBash owns NO timing: it kills the process group when its `spec.signal` + * fires and does not distinguish a timeout from a cancel. The executor fuses + * timeout + upstream cancellation into that one signal via + * `@deepseek-ai/dsh-timeout`'s `deadline`, and classifies the outcome from the + * signal afterward — the timing/classification half is shared, the kill is not. + * * Design notes (surveyed against Claude Code, OpenCode, Codex, and pi — see * the package README): spawn-per-call with `detached: true` so the child * leads its own process group; kills target the group (`kill(-pid)`) so @@ -69,13 +75,17 @@ export function childEnv(extra?: Record): NodeJS.ProcessEnv { export interface SpawnSpec { command: string cwd: string - /** Kill the process group after this many milliseconds. 0 = no timeout. */ - timeoutMs: number /** Per-stream in-memory cap; overflow spills to disk (tail kept in memory). */ maxOutputBytes: number /** Grace period between the SIGTERM and the SIGKILL escalation on a kill. */ graceMs: number - /** Abort signal — kills the process group when fired. */ + /** + * Abort signal — kills the process group when it fires. The executor owns + * timing: `run()` passes a fused timeout/cancel deadline signal (see + * `@deepseek-ai/dsh-timeout`), `start()` passes the bare upstream signal. + * runBash only listens and kills; it does NOT classify why (the executor + * reads the signal's reason afterward). + */ signal?: AbortSignal | undefined /** * Bytes to write to the child's stdin, then close it. Absent (or empty) @@ -92,12 +102,15 @@ export interface SpawnSpec { env?: Record | undefined } -/** Raw outcome of one closed process (before result shaping). */ +/** + * Raw outcome of one closed process (before result shaping). Deliberately + * carries NO timeout/cancel classification: runBash kills on abort but does not + * decide why — the executor's `run()`/`start()` reads the deadline signal it + * owns to classify `timedOut`/`aborted` (see the package README). + */ export interface SpawnOutcome { exitCode: number | null signal: NodeJS.Signals | null - timedOut: boolean - aborted: boolean stdout: CollectedOutput stderr: CollectedOutput } @@ -318,9 +331,6 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB child.stdout.on('data', (chunk: Buffer) => { stdout.push(chunk) }) child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk) }) - let timedOut = false - let aborted = false - let killTimer: NodeJS.Timeout | undefined let graceTimer: NodeJS.Timeout | undefined // pid is undefined when the spawn itself fails (bad cwd, missing binary); @@ -333,17 +343,12 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB graceTimer = setTimeout(() => { killGroup(pid, 'SIGKILL') }, spec.graceMs) } - if (spec.timeoutMs > 0) { - killTimer = setTimeout(() => { - timedOut = true - kill() - }, spec.timeoutMs) - } - - const onAbort = (): void => { - aborted = true - kill() - } + // runBash owns no timer: the executor's `run()` fuses timeout+cancel into one + // deadline signal (`@deepseek-ai/dsh-timeout`) and passes it here; we only + // listen and run the SIGTERM→grace→SIGKILL kill. Whether the abort was a + // timeout or an upstream cancel is classified by the executor from that + // signal, not tracked here. + const onAbort = (): void => { kill() } spec.signal?.addEventListener('abort', onAbort, { once: true }) // Write stdin and close it, but ONLY when the caller supplied bytes — with no @@ -376,14 +381,11 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB resolve({ exitCode, signal, - timedOut, - aborted, stdout: stdout.finalize(), stderr: stderr.finalize(), }) }) function cleanup(): void { - if (killTimer !== undefined) clearTimeout(killTimer) if (graceTimer !== undefined) clearTimeout(graceTimer) spec.signal?.removeEventListener('abort', onAbort) } diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts index ce89b2a0ae..fcd06b8bb3 100644 --- a/packages/bash/bash-local/tests/executor.spec.ts +++ b/packages/bash/bash-local/tests/executor.spec.ts @@ -101,6 +101,8 @@ describe('LocalBashExecutor.run', () => { const { bash } = await setup({ timeoutMs: 60_000 }) const result = await bash.run(bash.resolve({ command: 'sleep 60', timeoutMs: 100 })) expect(result.timedOut).toBe(true) + // Mutually exclusive: a timeout classifies as timedOut, never also aborted. + expect(result.aborted).toBe(false) expect(result.timeoutMs).toBe(100) }) @@ -111,6 +113,20 @@ describe('LocalBashExecutor.run', () => { setTimeout(() => { controller.abort() }, 50) const result = await pending expect(result.aborted).toBe(true) + // Mutually exclusive: an upstream cancel classifies as aborted, never also timedOut. + expect(result.timedOut).toBe(false) + }) + + it('classifies a self-killed command as neither timed out nor aborted', async () => { + // The command kills itself (SIGTERM) with no timeout and no upstream abort: + // the deadline signal never fires, so both classifications are false — the + // fused-signal classification reports the cause that cut the command short, + // and here nothing the executor owns did. + const { bash } = await setup({ timeoutMs: 60_000 }) + const result = await bash.run(bash.resolve({ command: 'kill -TERM $$' })) + expect(result.signal).toBe('SIGTERM') + expect(result.timedOut).toBe(false) + expect(result.aborted).toBe(false) }) it('rejects on spawn failure (bad workdir)', async () => { diff --git a/packages/bash/bash-local/tests/run.spec.ts b/packages/bash/bash-local/tests/run.spec.ts index d2888e2fee..1103637b92 100644 --- a/packages/bash/bash-local/tests/run.spec.ts +++ b/packages/bash/bash-local/tests/run.spec.ts @@ -26,7 +26,6 @@ function spec(command: string, overrides: Partial[0]> return { command, cwd: process.cwd(), - timeoutMs: 0, maxOutputBytes: 64_000, graceMs: 3_000, ...overrides, @@ -61,8 +60,6 @@ describe('runBash', () => { const result = await runBash(spec('echo hello')).done expect(result.exitCode).toBe(0) expect(result.signal).toBeNull() - expect(result.timedOut).toBe(false) - expect(result.aborted).toBe(false) expect(result.stdout.text).toBe('hello\n') expect(result.stdout.truncated).toBe(false) expect(result.stderr.text).toBe('') @@ -97,11 +94,16 @@ describe('runBash', () => { expect(result.stdout.text.trim()).toMatch(/\/tmp$/) }) - it('kills with SIGTERM on timeout', async () => { + it('kills the process group with SIGTERM when the signal fires', async () => { + // runBash owns no timer: it kills on abort. The executor drives the timeout + // by firing this signal via a deadline (see executor.spec.ts); here we + // assert the kill itself lands as SIGTERM. + const controller = new AbortController() const start = Date.now() - const result = await runBash(spec('sleep 60', { timeoutMs: 100 })).done + const running = runBash(spec('sleep 60', { signal: controller.signal })) + setTimeout(() => { controller.abort('deadline') }, 100) + const result = await running.done expect(Date.now() - start).toBeLessThan(5_000) - expect(result.timedOut).toBe(true) expect(result.signal).toBe('SIGTERM') expect(result.exitCode).toBeNull() }) @@ -134,7 +136,6 @@ describe('runBash', () => { const running = runBash(spec('sleep 60', { signal: controller.signal })) setTimeout(() => { controller.abort('user cancelled') }, 50) const result = await running.done - expect(result.aborted).toBe(true) expect(result.signal).toBe('SIGTERM') }) @@ -211,7 +212,6 @@ describe('stdin and extra env (set by in-process plugins)', () => { const big = 'x'.repeat(1024 * 1024) const result = await runBash(spec('exit 7', { stdin: big })).done expect(result.exitCode).toBe(7) - expect(result.aborted).toBe(false) }) }) @@ -339,11 +339,11 @@ describe('abort edge cases', () => { .toThrow(/aborted before spawn: aborted/) }) - it('reports an externally self-killed command without the timeout marker', async () => { + it('reports the terminating signal of an externally self-killed command', async () => { + // runBash reports the raw signal; whether it counts as timeout/cancel is the + // executor's classification (a self-kill is neither) — see executor.spec.ts. const result = await runBash(spec('kill -TERM $$')).done expect(result.signal).toBe('SIGTERM') - expect(result.timedOut).toBe(false) - expect(result.aborted).toBe(false) }) }) @@ -396,10 +396,9 @@ describe('review fixes: env scrubbing and spill hardening', () => { it('honors AbortSignal on background-style runs (no timeout)', async () => { const controller = new AbortController() - const running = runBash(spec('sleep 60', { timeoutMs: 0, signal: controller.signal })) + const running = runBash(spec('sleep 60', { signal: controller.signal })) setTimeout(() => { controller.abort() }, 50) const result = await running.done - expect(result.aborted).toBe(true) expect(result.signal).toBe('SIGTERM') }) }) diff --git a/packages/bash/bash-local/tsconfig.json b/packages/bash/bash-local/tsconfig.json index ae31546543..02448770f4 100644 --- a/packages/bash/bash-local/tsconfig.json +++ b/packages/bash/bash-local/tsconfig.json @@ -20,6 +20,9 @@ { "path": "../../util/brand" }, + { + "path": "../../util/timeout" + }, { "path": "../../bash/bash" } diff --git a/packages/fs/README.md b/packages/fs/README.md index 985a9f3ad6..04f979b59f 100644 --- a/packages/fs/README.md +++ b/packages/fs/README.md @@ -10,3 +10,8 @@ The filesystem stack: a provider seam (text IO + atomic mutation with an optiona | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`) | (registers on `ctx.tools`) | The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas. The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. + +## No timeouts on file IO + +`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web, which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md). A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries. + diff --git a/packages/util/README.md b/packages/util/README.md index ae73c8125f..45afe7b0a9 100644 --- a/packages/util/README.md +++ b/packages/util/README.md @@ -5,5 +5,8 @@ Zero-dependency primitives shared across the other groups. A package lands here | Package | Role | |---|---| | `brand/` | The type-only `Branded` nominal-typing primitive (no runtime code, no harness deps) | +| `timeout/` | The timing/classification half of a timeout — `clampTimeout`/`deadline`/`timeoutOf`/`TimeoutReason` (pure functions, no harness deps); termination stays in each capability | `dsh-brand` is the canonical case: it owns ONLY the `Branded` helper, so a capability package can brand the ids it owns (`dsh-bash`'s `BashTaskId`/`OwnerToken`, `dsh-session`'s `SessionId`, …) by depending on `dsh-brand` alone, without pulling in an unrelated package just to reach `Branded`. + +`dsh-timeout` follows the same shape for the timeout family: `dsh-bash` and `dsh-web-fetch-local` each fuse a caller's cancellation with a deadline and later classify "timed out" vs "cancelled" by depending on `dsh-timeout` alone. It deliberately owns only the timing/classification half — the *termination* (SIGKILL a process group, tear down a fetch socket) stays in each capability, because no shared layer can own every capability's kill (see [the timeout-library RFC](../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md)). diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md new file mode 100644 index 0000000000..4aa4485108 --- /dev/null +++ b/packages/util/timeout/README.md @@ -0,0 +1,40 @@ +# dsh-timeout + +The **timing-and-classification** half of a timeout — a zero-dependency library of pure functions (no runtime harness deps) shared by every capability that clamps a caller's timeout hint, arms a deadline, and later has to tell "timed out" apart from "cancelled". + +It owns **no termination**. The signal it hands out only *notifies*; actually stopping the work stays in each capability, because that mechanism differs — bash SIGKILLs an OS process group, web tears down a `fetch` socket — and no shared layer can own all of them. This is the boundary the [RFC](../../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md) draws: share the timing/classification, keep the hard kill local. + +It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state, emits no events. A "timeout service" would have to understand how to stop every capability's work — exactly the knowledge a microkernel keeps out of shared layers. + +## Surface + +```ts +import { clampTimeout, deadline, timeoutOf, TimeoutReason } from '@deepseek-ai/dsh-timeout' +``` + +| Export | Role | +|---|---| +| `clampTimeout(requested, def, max, name?)` | Validate the caller's optional positive-finite hint, fill from `def`, cap at `max`. Throws (with `name`) on a non-positive/non-finite hint. | +| `deadline(upstream, timeoutMs, code)` | Fuse `upstream` cancellation with a timeout into one `AbortSignal` (`AbortSignal.any`); the timeout carries a `TimeoutReason`. `[Symbol.dispose]` clears the timer. | +| `timeoutOf(signal \| { reason })` | Recover the `TimeoutReason` from an aborted signal/error, else `undefined` — the timeout-vs-cancel classifier. | +| `TimeoutReason` | The internal reason (`code` + `timeoutMs`) stamped on a timeout abort. Not a public error — providers translate it into their own error/field. | + +## The `timeoutMs <= 0` sentinel + +`0` is the **internal** "no timeout" value for backend-owned background work (bash `start()`): `deadline()` arms no timer and forwards only `upstream`; with no upstream either, it returns a never-aborting signal plus a no-op disposer, so every caller keeps one call shape. External request hints validate as **positive finite** via `clampTimeout` before they reach `deadline`, so `0` is never a model-/plugin-facing "disable timeout" value. + +## Usage shape + +```ts ignore-check +// Scope-lifetime consumer (foreground bash, one fetch): `using` disposes the timer. +using d = deadline(upstream, timeoutMs, 'BASH_TIMEOUT') +const outcome = await runWork({ signal: d.signal }) // work listens on d.signal and terminates itself +const timedOut = timeoutOf(d.signal) !== undefined // classify the first abort +const aborted = d.signal.aborted && !timedOut // mutually exclusive: timeout won, or cancel did +``` + +The signal only *notifies* — the caller MUST attach its own termination (`d.signal.addEventListener('abort', kill)`, or hand `d.signal` to `fetch`). Racing a promise against a timer would resolve the tool-call while the child process or socket leaks on; handing out a signal forces a real termination path to exist. + +## What does NOT get a timeout + +Local file `read`/`write`/`edit` take no `timeoutMs`: a syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. See [`fs/`](../../fs/README.md). diff --git a/packages/util/timeout/package.json b/packages/util/timeout/package.json new file mode 100644 index 0000000000..150a155324 --- /dev/null +++ b/packages/util/timeout/package.json @@ -0,0 +1,30 @@ +{ + "name": "@deepseek-ai/dsh-timeout", + "description": "Zero-dependency timeout/deadline primitive: clampTimeout, deadline, timeoutOf, TimeoutReason (timing + classification only, no termination)", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/util/timeout/src/index.ts b/packages/util/timeout/src/index.ts new file mode 100644 index 0000000000..dbfc76adb4 --- /dev/null +++ b/packages/util/timeout/src/index.ts @@ -0,0 +1,149 @@ +/** + * The timing-and-classification half of a timeout — a zero-dependency library + * of pure functions shared by every capability that clamps a caller's timeout + * hint, arms a deadline, and later has to tell "timed out" apart from + * "cancelled". It owns NO termination: the returned {@link deadline} signal only + * NOTIFIES; actually stopping the work (SIGKILL a process group, tear down a + * fetch socket, …) stays in each capability's implementation, because that + * mechanism differs per capability and no shared layer can own all of them. + * + * This is deliberately a library, not a cordis service or plugin: it takes no + * `ctx`, registers nothing, holds no cross-call state, and emits no events. A + * "timeout service" would have to understand how to stop every capability's + * work — exactly the knowledge a microkernel keeps out of shared layers. + * + * The four exports and their division of labor: + * - {@link clampTimeout} — validate a caller's optional positive hint, fill the + * backend default, cap at the backend max (pure arithmetic + the shared + * positive-finite request contract). + * - {@link deadline} — fuse upstream cancellation with a timeout into one + * `AbortSignal`, the timeout carrying an identifiable {@link TimeoutReason}; + * `[Symbol.dispose]` clears the timer. + * - {@link timeoutOf} — classify an aborted signal (or error): a + * {@link TimeoutReason} means the timeout fired, anything else (or nothing) + * means it did not. + * - {@link TimeoutReason} — the internal classification reason; providers + * translate it into their own public error/result shape before returning. + * + * @module @deepseek-ai/dsh-timeout + */ + +/** + * The internal reason attached to a timeout abort so consumers can classify it + * after the fact. It carries the failing `code` (each capability's own string — + * `BASH_TIMEOUT`, `WEB_FETCH_TIMEOUT`, …) and the `timeoutMs` that elapsed. + * + * It is an INTERNAL classification reason, not a public error: providers + * translate it into their seam-specific error code or result field (via + * {@link timeoutOf}) before returning to callers. Native `AbortSignal.timeout()` + * yields a fixed `TimeoutError` indistinguishable across timeout kinds; this + * type is identifiable and carries the code/duration. + */ +export class TimeoutReason extends Error { + override name = 'TimeoutReason' + + /** + * @param code Capability-owned timeout code (e.g. `BASH_TIMEOUT`). + * @param timeoutMs The deadline that elapsed, in milliseconds. + */ + constructor(readonly code: string, readonly timeoutMs: number) { + super(`${code} after ${timeoutMs}ms`) + } +} + +/** + * Validate a caller's optional timeout hint, fill it from the backend default, + * then cap at the backend max. The shared positive-finite request contract: + * a supplied `requested` must be a positive finite number or this throws — + * `0` is NOT a caller-facing "disable timeout" value (that sentinel is internal + * to {@link deadline}). A missing `requested` falls back to `def`. + * + * @param requested The caller's optional hint; validated when present. + * @param def The backend default applied when `requested` is absent. + * @param max The backend upper bound the result is capped to. + * @param name Field name used in the thrown message (so the caller sees which input was bad). + * @returns The effective timeout in milliseconds: `min(requested ?? def, max)`. + */ +export function clampTimeout( + requested: number | undefined, + def: number, + max: number, + name = 'timeoutMs', +): number { + if (requested !== undefined && (!Number.isFinite(requested) || requested <= 0)) { + throw new Error(`${name} must be a positive finite number`) + } + return Math.min(requested ?? def, max) +} + +/** A deadline signal plus the cleanup that clears its timer (dispose-once). */ +export interface Deadline { + /** Aborts on upstream cancellation OR on timeout (the timeout carries a {@link TimeoutReason}). */ + readonly signal: AbortSignal + /** Clear the timer. Safe to call once; `using` calls it at scope exit. */ + [Symbol.dispose](): void +} + +/** + * Build a deadline signal that aborts on upstream cancellation OR on timeout, + * with the timeout carrying an identifiable {@link TimeoutReason} (unlike + * native `AbortSignal.timeout()`, whose fixed `TimeoutError` is opaque). It is + * `AbortSignal.any([upstream, ])` — the single primitive that fuses + * two abort sources — with the reason and a disposable timer added on top. + * + * `timeoutMs <= 0` is the INTERNAL "no timeout" sentinel for backend-owned + * background work: arm no timer and forward only the upstream signal; with no + * upstream either, return a never-aborting signal so callers keep one call + * shape. External request hints validate as positive finite via + * {@link clampTimeout} before reaching here, so `0` never arrives from a model + * or plugin. + * + * The returned object's `[Symbol.dispose]` clears the timer — use `using` for a + * scope-lifetime consumer, or call it manually for an event-lifetime one. The + * signal only NOTIFIES; the caller must attach its own termination (kill the + * process group, abort the fetch, …). + * + * @param upstream The caller's cancellation signal, if any, fused into the result. + * @param timeoutMs Deadline in milliseconds; `<= 0` means "no timeout" (arm no timer). + * @param code Capability-owned code stamped onto the timeout's {@link TimeoutReason}. + * @returns The fused {@link Deadline} (signal + timer cleanup). + */ +export function deadline( + upstream: AbortSignal | undefined, + timeoutMs: number, + code: string, +): Deadline { + if (timeoutMs <= 0) { + // No timeout (background work): forward only the upstream signal, or a + // never-aborting one when there is no upstream. No timer, so dispose is a + // no-op — the empty method keeps the one call shape for every caller. + return { signal: upstream ?? new AbortController().signal, [Symbol.dispose]() {} } + } + + const timer = new AbortController() + const id = setTimeout(() => { timer.abort(new TimeoutReason(code, timeoutMs)) }, timeoutMs) + return { + // AbortSignal.any adopts the reason of whichever source aborts FIRST, so a + // race resolves to a single cause: timeoutOf() reads TimeoutReason only + // when the timeout won, and upstream-wins leaves an ordinary abort reason. + signal: upstream !== undefined ? AbortSignal.any([upstream, timer.signal]) : timer.signal, + [Symbol.dispose]() { clearTimeout(id) }, + } +} + +/** + * Recover the {@link TimeoutReason} from an aborted signal (or any object with a + * `reason`), else `undefined`. This is the classification half: a provider + * calls it on the deadline signal after an abort to decide whether the cause + * was its timeout (translate to the capability's timeout error/field) or an + * ordinary upstream cancellation (`undefined` → the cancel path). + * + * @param x An {@link AbortSignal} or any `{ reason }` carrier (e.g. a caught abort error). + * @returns The {@link TimeoutReason} when the abort was a timeout, else `undefined`. + */ +export function timeoutOf(x: AbortSignal | { reason?: unknown }): TimeoutReason | undefined { + // AbortSignal.reason is typed `any`; pin it to `unknown` so no `any` leaks and + // the instanceof narrows cleanly for both a signal and a bare reason carrier. + const reason: unknown = x.reason + return reason instanceof TimeoutReason ? reason : undefined +} diff --git a/packages/util/timeout/tests/timeout.spec.ts b/packages/util/timeout/tests/timeout.spec.ts new file mode 100644 index 0000000000..4e60cf35b7 --- /dev/null +++ b/packages/util/timeout/tests/timeout.spec.ts @@ -0,0 +1,160 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { clampTimeout, deadline, timeoutOf, TimeoutReason } from '@deepseek-ai/dsh-timeout' + +describe('TimeoutReason', () => { + it('is an Error carrying the code and elapsed ms', () => { + const reason = new TimeoutReason('BASH_TIMEOUT', 100) + expect(reason).toBeInstanceOf(Error) + expect(reason.name).toBe('TimeoutReason') + expect(reason.code).toBe('BASH_TIMEOUT') + expect(reason.timeoutMs).toBe(100) + expect(reason.message).toBe('BASH_TIMEOUT after 100ms') + }) +}) + +describe('clampTimeout', () => { + it('fills the default when the hint is absent', () => { + expect(clampTimeout(undefined, 120_000, 600_000)).toBe(120_000) + }) + + it('caps the hint at max', () => { + expect(clampTimeout(999_999, 120_000, 600_000)).toBe(600_000) + }) + + it('keeps a valid hint under the cap', () => { + expect(clampTimeout(5_000, 120_000, 600_000)).toBe(5_000) + }) + + it('caps the default itself when the default exceeds max', () => { + // min(def, max) applies even with no hint — a misconfigured backend never + // exceeds its own cap. + expect(clampTimeout(undefined, 900_000, 600_000)).toBe(600_000) + }) + + it('rejects a non-finite hint with the caller-provided name', () => { + expect(() => clampTimeout(Number.NaN, 100, 200, 'bash-local: request.timeoutMs')) + .toThrow(/bash-local: request\.timeoutMs must be a positive finite number/) + expect(() => clampTimeout(Number.POSITIVE_INFINITY, 100, 200)) + .toThrow(/timeoutMs must be a positive finite number/) + }) + + it('rejects a non-positive hint', () => { + expect(() => clampTimeout(0, 100, 200)).toThrow(/must be a positive finite number/) + expect(() => clampTimeout(-1, 100, 200)).toThrow(/must be a positive finite number/) + }) +}) + +describe('deadline — timeout arm', () => { + afterEach(() => { vi.useRealTimers() }) + + it('aborts on timeout with a TimeoutReason after the elapsed ms', () => { + vi.useFakeTimers() + using d = deadline(undefined, 100, 'BASH_TIMEOUT') + expect(d.signal.aborted).toBe(false) + vi.advanceTimersByTime(100) + expect(d.signal.aborted).toBe(true) + const reason = timeoutOf(d.signal) + expect(reason).toBeInstanceOf(TimeoutReason) + expect(reason?.code).toBe('BASH_TIMEOUT') + expect(reason?.timeoutMs).toBe(100) + }) + + it('[Symbol.dispose] clears the timer so no abort fires afterward', () => { + vi.useFakeTimers() + const d = deadline(undefined, 100, 'BASH_TIMEOUT') + d[Symbol.dispose]() + vi.advanceTimersByTime(1_000) + expect(d.signal.aborted).toBe(false) + expect(timeoutOf(d.signal)).toBeUndefined() + }) +}) + +describe('deadline — fuse with upstream', () => { + it('aborts on upstream cancellation, classified as NOT a timeout', () => { + const upstream = new AbortController() + using d = deadline(upstream.signal, 60_000, 'BASH_TIMEOUT') + upstream.abort('user cancelled') + expect(d.signal.aborted).toBe(true) + expect(timeoutOf(d.signal)).toBeUndefined() + }) + + it('cancel wins when it fires before the timeout', () => { + vi.useFakeTimers() + try { + const upstream = new AbortController() + using d = deadline(upstream.signal, 100, 'BASH_TIMEOUT') + upstream.abort('user cancelled') // fires first, before the 100ms timer + vi.advanceTimersByTime(200) + expect(d.signal.aborted).toBe(true) + // AbortSignal.any adopts the FIRST source's reason: cancel won, so no + // TimeoutReason even though the timer later elapsed. + expect(timeoutOf(d.signal)).toBeUndefined() + } finally { + vi.useRealTimers() + } + }) + + it('timeout wins when it fires before upstream cancellation', () => { + vi.useFakeTimers() + try { + const upstream = new AbortController() + using d = deadline(upstream.signal, 100, 'WEB_FETCH_TIMEOUT') + vi.advanceTimersByTime(100) // timer fires first + upstream.abort('too late') + expect(timeoutOf(d.signal)?.code).toBe('WEB_FETCH_TIMEOUT') + } finally { + vi.useRealTimers() + } + }) + + it('forwards a pre-aborted upstream signal immediately', () => { + const upstream = new AbortController() + upstream.abort('already gone') + using d = deadline(upstream.signal, 60_000, 'BASH_TIMEOUT') + expect(d.signal.aborted).toBe(true) + expect(timeoutOf(d.signal)).toBeUndefined() + }) +}) + +describe('deadline — timeoutMs <= 0 (no-timeout sentinel)', () => { + afterEach(() => { vi.useRealTimers() }) + + it('arms no timer and forwards only the upstream signal', () => { + vi.useFakeTimers() + const upstream = new AbortController() + using d = deadline(upstream.signal, 0, 'BASH_TIMEOUT') + vi.advanceTimersByTime(1_000_000) + expect(d.signal.aborted).toBe(false) // no timer ever armed + upstream.abort('kill') + expect(d.signal.aborted).toBe(true) + expect(timeoutOf(d.signal)).toBeUndefined() // never a timeout + }) + + it('returns a never-aborting signal with a no-op disposer when there is no upstream', () => { + vi.useFakeTimers() + const d = deadline(undefined, 0, 'BASH_TIMEOUT') + expect(() => { d[Symbol.dispose]() }).not.toThrow() + vi.advanceTimersByTime(1_000_000) + expect(d.signal.aborted).toBe(false) + expect(timeoutOf(d.signal)).toBeUndefined() + }) + + it('treats a negative timeout the same as zero', () => { + const d = deadline(undefined, -5, 'BASH_TIMEOUT') + expect(d.signal.aborted).toBe(false) + d[Symbol.dispose]() + }) +}) + +describe('timeoutOf', () => { + it('classifies a bare reason carrier that holds a TimeoutReason', () => { + const reason = new TimeoutReason('WEB_FETCH_TIMEOUT', 50) + expect(timeoutOf({ reason })).toBe(reason) + }) + + it('returns undefined for a non-timeout reason', () => { + expect(timeoutOf({ reason: new Error('other') })).toBeUndefined() + expect(timeoutOf({ reason: 'user cancelled' })).toBeUndefined() + expect(timeoutOf({})).toBeUndefined() + }) +}) diff --git a/packages/util/timeout/tsconfig.json b/packages/util/timeout/tsconfig.json new file mode 100644 index 0000000000..749cb0208e --- /dev/null +++ b/packages/util/timeout/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [] +} diff --git a/packages/web/web-fetch-local/package.json b/packages/web/web-fetch-local/package.json index 8d9a599a52..9b847db6f3 100644 --- a/packages/web/web-fetch-local/package.json +++ b/packages/web/web-fetch-local/package.json @@ -22,6 +22,7 @@ ], "license": "BSD-3-Clause", "peerDependencies": { + "@deepseek-ai/dsh-timeout": "^0.0.1", "@deepseek-ai/dsh-web": "^0.0.1", "cordis": "^4.0.0-rc.6" }, @@ -29,6 +30,7 @@ "schemastery": "^3.18.0" }, "devDependencies": { + "@deepseek-ai/dsh-timeout": "workspace:^", "@deepseek-ai/dsh-web": "workspace:^", "cordis": "^4.0.0-rc.6" } diff --git a/packages/web/web-fetch-local/src/provider.ts b/packages/web/web-fetch-local/src/provider.ts index 29b183b710..53fc57f621 100644 --- a/packages/web/web-fetch-local/src/provider.ts +++ b/packages/web/web-fetch-local/src/provider.ts @@ -21,6 +21,7 @@ import { WebError } from '@deepseek-ai/dsh-web' import type { WebFetchBody, WebFetchProvider, WebFetchRequest, WebFetchResult, WebProviderStatus } from '@deepseek-ai/dsh-web' +import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { classifyContentType, decoderForCharset, isSameOrigin, parseCharset, validateFetchUrl } from './policy.ts' /** Resolved provider limits (the plugin's schemastery Config supplies defaults). */ @@ -56,35 +57,25 @@ export class LocalFetchProvider implements WebFetchProvider { } async fetch(request: WebFetchRequest, exec?: { readonly signal?: AbortSignal }): Promise { - const timeoutMs = request.timeoutMs !== undefined - ? Math.min(request.timeoutMs, this.limits.maxTimeoutMs) - : this.limits.timeoutMs + if (exec?.signal?.aborted) throw new WebError('web fetch aborted', 'WEB_ABORTED') + const timeoutMs = clampTimeout(request.timeoutMs, this.limits.timeoutMs, this.limits.maxTimeoutMs) - // One controller drives both the caller's abort and our own timeout, so the - // network request and the streaming read both stop on either. - const controller = new AbortController() - const onAbort = (): void => { controller.abort() } - if (exec?.signal !== undefined) { - if (exec.signal.aborted) throw new WebError('web fetch aborted', 'WEB_ABORTED') - exec.signal.addEventListener('abort', onAbort, { once: true }) - } - const timer = setTimeout(() => { controller.abort(new WebError('web fetch timed out', 'WEB_FETCH_TIMEOUT')) }, timeoutMs) - - try { - return await this.followAndRead(request.url, controller) - } finally { - clearTimeout(timer) - if (exec?.signal !== undefined) exec.signal.removeEventListener('abort', onAbort) - } + // One deadline signal fuses the caller's abort with our own timeout, so the + // network request and the streaming read both stop on either. The timeout + // abort carries a TimeoutReason we recover afterward to classify the cause + // (translateAbortOrNetwork), instead of hand-rolling a controller + timer + + // reason-recovery dance. + using d = deadline(exec?.signal, timeoutMs, 'WEB_FETCH_TIMEOUT') + return await this.followAndRead(request.url, d.signal) } /** Follow same-origin redirects up to the hop cap, then read the final response. */ - private async followAndRead(initialUrl: string, controller: AbortController): Promise { + private async followAndRead(initialUrl: string, signal: AbortSignal): Promise { let currentUrl = validateFetchUrl(initialUrl, this.limits.maxUrlLength) let redirectsFollowed = 0 for (;;) { - const response = await this.requestOnce(currentUrl, controller) + const response = await this.requestOnce(currentUrl, signal) if (isRedirectStatus(response.status)) { // The redirect budget is enforced BEFORE this hop's target is resolved @@ -127,20 +118,20 @@ export class LocalFetchProvider implements WebFetchProvider { continue } - return await this.readBody(response, currentUrl, controller.signal) + return await this.readBody(response, currentUrl, signal) } } - private async requestOnce(url: URL, controller: AbortController): Promise { + private async requestOnce(url: URL, signal: AbortSignal): Promise { try { return await fetch(url, { method: 'GET', redirect: 'manual', headers: { 'user-agent': this.limits.userAgent, 'accept': 'text/html,application/xhtml+xml,text/*;q=0.9,application/json;q=0.8' }, - signal: controller.signal, + signal, }) } catch (error: unknown) { - throw translateAbortOrNetwork(error, controller.signal) + throw translateAbortOrNetwork(error, signal) } } @@ -255,24 +246,17 @@ function resolveRedirect(location: string, base: URL): URL { } /** - * Translate a thrown fetch/stream error into a `WebError`. Our own - * `WEB_FETCH_TIMEOUT` (passed to `controller.abort(reason)`) and any other - * already-typed `WebError` pass through; an `AbortError` becomes `WEB_ABORTED`, - * UNLESS the abort was our timeout — the body-read reader surfaces a generic - * `AbortError` rather than the abort reason, so we recover the timeout's - * `WebError` from `signal.reason`; anything else is a transport/network failure - * (`WEB_PROVIDER_ERROR`). + * Translate a thrown fetch/stream error into a `WebError`, classified by the + * deadline signal rather than the error's shape (which differs by phase: the + * request-phase `fetch` rejects with the abort reason, while the read-phase + * reader surfaces a bare `AbortError`). `timeoutOf(signal)` recovering a + * `TimeoutReason` means our timeout fired (`WEB_FETCH_TIMEOUT`); any other abort + * is upstream cancellation (`WEB_ABORTED`); a throw with the signal NOT aborted + * is a transport/network failure (`WEB_PROVIDER_ERROR`). */ -function translateAbortOrNetwork(error: unknown, signal?: AbortSignal): WebError { - if (error instanceof WebError) return error - if (error instanceof DOMException && error.name === 'AbortError') { - // A timeout abort carries its WebError as the signal reason; honor the - // WEB_FETCH_TIMEOUT contract instead of reporting a generic cancellation. - // (Node rejects WITH the reason — the WebError branch above — so this only - // fires on a runtime that surfaces a bare AbortError while reason is set.) - /* v8 ignore next */ - if (signal?.reason instanceof WebError) return signal.reason - return new WebError('web fetch aborted', 'WEB_ABORTED', { cause: error }) - } +function translateAbortOrNetwork(error: unknown, signal: AbortSignal): WebError { + const timeout = timeoutOf(signal) + if (timeout !== undefined) return new WebError('web fetch timed out', 'WEB_FETCH_TIMEOUT', { cause: timeout }) + if (signal.aborted) return new WebError('web fetch aborted', 'WEB_ABORTED', { cause: error }) return new WebError(`web fetch failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error }) } diff --git a/packages/web/web-fetch-local/tsconfig.json b/packages/web/web-fetch-local/tsconfig.json index aa7c949fec..c6fb75a5c1 100644 --- a/packages/web/web-fetch-local/tsconfig.json +++ b/packages/web/web-fetch-local/tsconfig.json @@ -17,6 +17,9 @@ { "path": "../../../vendor/schemastery" }, + { + "path": "../../util/timeout" + }, { "path": "../web" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d5fb68c746..54050bd0f4 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -93,6 +93,9 @@ importers: '@deepseek-ai/dsh-bash': specifier: workspace:^ version: link:../bash + '@deepseek-ai/dsh-timeout': + specifier: workspace:^ + version: link:../../util/timeout cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -960,6 +963,12 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/util/timeout: + devDependencies: + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/web/tool-web: dependencies: schemastery: @@ -1013,6 +1022,9 @@ importers: specifier: ^3.18.0 version: 3.18.0 devDependencies: + '@deepseek-ai/dsh-timeout': + specifier: workspace:^ + version: link:../../util/timeout '@deepseek-ai/dsh-web': specifier: workspace:^ version: link:../web diff --git a/tsconfig.build.json b/tsconfig.build.json index b6ba7901f2..ebf8ffef14 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -11,6 +11,7 @@ { "path": "./vendor/hmr" }, { "path": "./vendor/logger-console" }, { "path": "./packages/util/brand" }, + { "path": "./packages/util/timeout" }, { "path": "./packages/llm/llm" }, { "path": "./packages/core/session" }, { "path": "./packages/session-persistence/session-persistence" }, diff --git a/tsconfig.json b/tsconfig.json index 9cd7aa8a6d..49cce594dd 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -22,6 +22,7 @@ { "path": "./vendor/hmr" }, { "path": "./vendor/logger-console" }, { "path": "./packages/util/brand" }, + { "path": "./packages/util/timeout" }, { "path": "./packages/llm/llm" }, { "path": "./packages/core/session" }, { "path": "./packages/session-persistence/session-persistence" }, From b4ba84a1a941add356982419c6c8eeaaa30f371f Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Mon, 6 Jul 2026 16:46:14 +0800 Subject: [PATCH 019/119] fix: drop trailing blank line in fs README (codex review round 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 1 P3: the "No timeouts on file IO" section left the file ending in a blank line, which the trailing-newline whitespace gate rejects. Declined P2 (late abort after a timeout is lost): that is the RFC's decided trade-off — mutually-exclusive first-abort classification — and re-latching aborted would violate the acceptance criterion. --- packages/fs/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/fs/README.md b/packages/fs/README.md index 04f979b59f..ec3bb62afb 100644 --- a/packages/fs/README.md +++ b/packages/fs/README.md @@ -14,4 +14,3 @@ The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesyst ## No timeouts on file IO `read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web, which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md). A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries. - From 760bc9aa6a9d3517f6c3e90a910da653652826ce Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Mon, 6 Jul 2026 17:07:11 +0800 Subject: [PATCH 020/119] fix: scope timeoutOf by deadline code so nesting composes (codex round 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 2 P2: timeoutOf() accepted ANY TimeoutReason, so under nesting — when the upstream handed to deadline() is itself a deadline (the RFC's named tools/execute middleware follow-up) and its outer timer fires first — AbortSignal.any preserves the outer reason and the inner bash/web would report the outer timeout as their own (timedOut / WEB_FETCH_TIMEOUT) though their local timer never expired. Add an optional code to timeoutOf; bash and web pass their own code, so a foreign timeout falls through to the upstream-cancel path. --- .../2026-07-06-timeout-deadline-library.md | 8 +++---- packages/bash/bash-local/src/index.ts | 11 +++++----- packages/util/timeout/README.md | 10 +++++---- packages/util/timeout/src/index.ts | 19 ++++++++++++++--- packages/util/timeout/tests/timeout.spec.ts | 21 +++++++++++++++++++ packages/web/web-fetch-local/src/provider.ts | 11 +++++----- 6 files changed, 59 insertions(+), 21 deletions(-) diff --git a/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md b/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md index 84fc5b3ea2..4902a0e833 100644 --- a/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md +++ b/docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md @@ -53,11 +53,11 @@ export function deadline( code: string, ): { signal: AbortSignal; [Symbol.dispose](): void } -/** Recover the TimeoutReason from an aborted signal (or error), else undefined. */ -export function timeoutOf(x: AbortSignal | { reason?: unknown }): TimeoutReason | undefined +/** Recover the TimeoutReason from an aborted signal (or error); `code` scopes the match to this deadline's timer. */ +export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): TimeoutReason | undefined ``` -`deadline` is `AbortSignal.any([upstream, ])` with three things the standard library does not give: a typed, identifiable `TimeoutReason` on the timeout abort (native `AbortSignal.timeout()` yields a fixed `TimeoutError`, indistinguishable across timeout kinds), an internal `timeoutMs <= 0` "no timeout" sentinel for backend-owned background work, and a `Symbol.dispose` cleanup that works with both `using` and manual disposal. `AbortSignal.any` is a Node ≥ 20 primitive; it is the single mechanism that fuses two abort sources into one, adopting the reason of whichever fires first. External request hints validate as positive finite numbers via `clampTimeout` before they reach `deadline`; `0` is not a model-/plugin-facing "disable timeout" value. When `timeoutMs <= 0` and no upstream signal is present, `deadline()` returns a never-aborting signal plus a no-op disposer so callers keep one call shape. `TimeoutReason` is an internal classification reason: providers translate it into seam-specific public errors or result fields before returning to callers. +`deadline` is `AbortSignal.any([upstream, ])` with three things the standard library does not give: a typed, identifiable `TimeoutReason` on the timeout abort (native `AbortSignal.timeout()` yields a fixed `TimeoutError`, indistinguishable across timeout kinds), an internal `timeoutMs <= 0` "no timeout" sentinel for backend-owned background work, and a `Symbol.dispose` cleanup that works with both `using` and manual disposal. `AbortSignal.any` is a Node ≥ 20 primitive; it is the single mechanism that fuses two abort sources into one, adopting the reason of whichever fires first. External request hints validate as positive finite numbers via `clampTimeout` before they reach `deadline`; `0` is not a model-/plugin-facing "disable timeout" value. When `timeoutMs <= 0` and no upstream signal is present, `deadline()` returns a never-aborting signal plus a no-op disposer so callers keep one call shape. `TimeoutReason` is an internal classification reason: providers translate it into seam-specific public errors or result fields before returning to callers. `timeoutOf`'s optional `code` scopes classification to the caller's own deadline: when the `upstream` is itself a deadline (a future `tools/execute` middleware arming a per-call deadline), `AbortSignal.any` preserves the outer `TimeoutReason` if it fires first, and an unscoped match would misreport the outer timeout as the inner capability's own; scoping to `code` reads a foreign timeout as an ordinary upstream cancel. ### The division of labor @@ -76,7 +76,7 @@ The signal only *notifies*; termination is always the listener's job, and the li ### How each capability consumes it - **web_fetch** — the tool stays validate-and-forward; the provider's hand-rolled controller + `setTimeout` + manual listener + `finally` + `signal.reason` recovery is replaced by provider-owned `deadline`/`timeoutOf`. A pre-aborted upstream signal still throws `WEB_ABORTED` up front; otherwise `fetch` runs against the fused `d.signal`, and `translateAbortOrNetwork` classifies a thrown error by the signal (`timeoutOf` → `WEB_FETCH_TIMEOUT`, else aborted → `WEB_ABORTED`, else network → `WEB_PROVIDER_ERROR`). The public error-code contract is unchanged, and `TimeoutReason` never crosses the web seam as the public error. -- **bash** — `resolve()` stays a pure request-to-spec step: it clamps with `clampTimeout(request.timeoutMs, config.timeoutMs, config.maxTimeoutMs, 'bash-local: request.timeoutMs')` and carries `request.signal` through unchanged. Foreground `run()` owns the timeout: `using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')`, then `runBash` receives only `d.signal`. `runBash` no longer owns any timer — it listens for abort and runs its existing SIGTERM→grace→SIGKILL process-group kill, and its `SpawnSpec`/`SpawnOutcome` no longer carry `timeoutMs`/`timedOut`/`aborted` (the executor classifies from the deadline signal instead). `run()` computes `timedOut = timeoutOf(d.signal) !== undefined` and `aborted = d.signal.aborted && !timedOut`, so the public seam booleans (`BashRunResult.timedOut`/`aborted`) are mutually exclusive — the shared deadline reports the cause that first cut the command short. Background `start()` creates no deadline and forwards only the upstream signal, so background tasks stay timeout-free; a task's killed-vs-completed status reads its own `spec.signal.aborted`. +- **bash** — `resolve()` stays a pure request-to-spec step: it clamps with `clampTimeout(request.timeoutMs, config.timeoutMs, config.maxTimeoutMs, 'bash-local: request.timeoutMs')` and carries `request.signal` through unchanged. Foreground `run()` owns the timeout: `using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')`, then `runBash` receives only `d.signal`. `runBash` no longer owns any timer — it listens for abort and runs its existing SIGTERM→grace→SIGKILL process-group kill, and its `SpawnSpec`/`SpawnOutcome` no longer carry `timeoutMs`/`timedOut`/`aborted` (the executor classifies from the deadline signal instead). `run()` computes `timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined` and `aborted = d.signal.aborted && !timedOut`, so the public seam booleans (`BashRunResult.timedOut`/`aborted`) are mutually exclusive — the shared deadline reports the cause that first cut the command short, and the `code` scope keeps a nested outer deadline from being misread as bash's own timeout. Background `start()` creates no deadline and forwards only the upstream signal, so background tasks stay timeout-free; a task's killed-vs-completed status reads its own `spec.signal.aborted`. ## Consequences diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts index 674f410b50..3e09d7e35b 100644 --- a/packages/bash/bash-local/src/index.ts +++ b/packages/bash/bash-local/src/index.ts @@ -150,11 +150,12 @@ export class LocalBashExecutor extends BashExecutor { stdin: spec.stdin, env: spec.env, }, this.internals).done - // Classify the FIRST abort reason: a TimeoutReason means the timeout cut the - // command short; any other abort is upstream cancellation. Mutually - // exclusive by construction — the fused signal reports one cause, not two - // independently-latched facts. - const timedOut = timeoutOf(d.signal) !== undefined + // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our + // timeout cut the command short; any other abort — an upstream cancel, or a + // foreign (outer) deadline's timeout under nesting — is aborted. Scoping to + // our own code keeps a nested outer deadline from reading as our timeout. + // Mutually exclusive by construction — the fused signal reports one cause. + const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined const aborted = d.signal.aborted && !timedOut return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs } } diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md index 4aa4485108..db2b06ba53 100644 --- a/packages/util/timeout/README.md +++ b/packages/util/timeout/README.md @@ -16,7 +16,7 @@ import { clampTimeout, deadline, timeoutOf, TimeoutReason } from '@deepseek-ai/d |---|---| | `clampTimeout(requested, def, max, name?)` | Validate the caller's optional positive-finite hint, fill from `def`, cap at `max`. Throws (with `name`) on a non-positive/non-finite hint. | | `deadline(upstream, timeoutMs, code)` | Fuse `upstream` cancellation with a timeout into one `AbortSignal` (`AbortSignal.any`); the timeout carries a `TimeoutReason`. `[Symbol.dispose]` clears the timer. | -| `timeoutOf(signal \| { reason })` | Recover the `TimeoutReason` from an aborted signal/error, else `undefined` — the timeout-vs-cancel classifier. | +| `timeoutOf(signal \| { reason }, code?)` | Recover the `TimeoutReason` from an aborted signal/error, else `undefined` — the timeout-vs-cancel classifier. Pass `code` to match only THIS deadline's timer (see nesting below). | | `TimeoutReason` | The internal reason (`code` + `timeoutMs`) stamped on a timeout abort. Not a public error — providers translate it into their own error/field. | ## The `timeoutMs <= 0` sentinel @@ -28,13 +28,15 @@ import { clampTimeout, deadline, timeoutOf, TimeoutReason } from '@deepseek-ai/d ```ts ignore-check // Scope-lifetime consumer (foreground bash, one fetch): `using` disposes the timer. using d = deadline(upstream, timeoutMs, 'BASH_TIMEOUT') -const outcome = await runWork({ signal: d.signal }) // work listens on d.signal and terminates itself -const timedOut = timeoutOf(d.signal) !== undefined // classify the first abort -const aborted = d.signal.aborted && !timedOut // mutually exclusive: timeout won, or cancel did +const outcome = await runWork({ signal: d.signal }) // work listens on d.signal and terminates itself +const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined // classify the first abort, scoped to OUR code +const aborted = d.signal.aborted && !timedOut // mutually exclusive: timeout won, or cancel did ``` The signal only *notifies* — the caller MUST attach its own termination (`d.signal.addEventListener('abort', kill)`, or hand `d.signal` to `fetch`). Racing a promise against a timer would resolve the tool-call while the child process or socket leaks on; handing out a signal forces a real termination path to exist. +Pass your own `code` to `timeoutOf` so classification composes under nesting: when the `upstream` you were handed is *itself* a deadline signal (a future `tools/execute` middleware arming a per-call deadline), `AbortSignal.any` preserves the outer `TimeoutReason` if the outer timer fires first. Scoping to your `code` makes a foreign timeout read as an ordinary upstream cancel — the correct classification from your capability's view — instead of your own timeout firing when your local timer never expired. + ## What does NOT get a timeout Local file `read`/`write`/`edit` take no `timeoutMs`: a syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. See [`fs/`](../../fs/README.md). diff --git a/packages/util/timeout/src/index.ts b/packages/util/timeout/src/index.ts index dbfc76adb4..ed95a877d3 100644 --- a/packages/util/timeout/src/index.ts +++ b/packages/util/timeout/src/index.ts @@ -138,12 +138,25 @@ export function deadline( * was its timeout (translate to the capability's timeout error/field) or an * ordinary upstream cancellation (`undefined` → the cancel path). * + * Pass `code` to scope the match to THIS deadline's timer. It matters under + * nesting: when the `upstream` handed to {@link deadline} is itself a deadline + * signal (e.g. a future `tools/execute` middleware arming a per-call deadline), + * `AbortSignal.any` preserves the OUTER `TimeoutReason` if the outer timer fires + * first. Without `code`, the inner capability would misclassify that outer + * timeout as its own (`timedOut:true` / `WEB_FETCH_TIMEOUT`) though its local + * timer never expired; with `code`, a foreign timeout reads as `undefined` and + * falls through to the upstream-cancel path, which is the correct classification + * from the inner capability's view. Omit `code` only to ask "was this ANY + * timeout" (a generic middleware that owns no single code). + * * @param x An {@link AbortSignal} or any `{ reason }` carrier (e.g. a caught abort error). - * @returns The {@link TimeoutReason} when the abort was a timeout, else `undefined`. + * @param code When provided, only a {@link TimeoutReason} with this exact `code` matches. + * @returns The matching {@link TimeoutReason}, else `undefined`. */ -export function timeoutOf(x: AbortSignal | { reason?: unknown }): TimeoutReason | undefined { +export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): TimeoutReason | undefined { // AbortSignal.reason is typed `any`; pin it to `unknown` so no `any` leaks and // the instanceof narrows cleanly for both a signal and a bare reason carrier. const reason: unknown = x.reason - return reason instanceof TimeoutReason ? reason : undefined + if (!(reason instanceof TimeoutReason)) return undefined + return code === undefined || reason.code === code ? reason : undefined } diff --git a/packages/util/timeout/tests/timeout.spec.ts b/packages/util/timeout/tests/timeout.spec.ts index 4e60cf35b7..57066a4f54 100644 --- a/packages/util/timeout/tests/timeout.spec.ts +++ b/packages/util/timeout/tests/timeout.spec.ts @@ -157,4 +157,25 @@ describe('timeoutOf', () => { expect(timeoutOf({ reason: 'user cancelled' })).toBeUndefined() expect(timeoutOf({})).toBeUndefined() }) + + it('matches only the requested code when one is given', () => { + const reason = new TimeoutReason('BASH_TIMEOUT', 100) + expect(timeoutOf({ reason }, 'BASH_TIMEOUT')).toBe(reason) + expect(timeoutOf({ reason }, 'WEB_FETCH_TIMEOUT')).toBeUndefined() + }) +}) + +describe('deadline — nested deadlines', () => { + it("does not misclassify an outer deadline's timeout as the inner code", () => { + // The upstream handed to the inner deadline is ITSELF a deadline that has + // already timed out (outer). AbortSignal.any preserves the outer reason; + // scoping timeoutOf to the inner code keeps the inner capability from + // reporting the outer timeout as its own — it reads as an upstream cancel. + const outer = new AbortController() + outer.abort(new TimeoutReason('OUTER_TIMEOUT', 30)) + using inner = deadline(outer.signal, 60_000, 'BASH_TIMEOUT') + expect(inner.signal.aborted).toBe(true) + expect(timeoutOf(inner.signal, 'BASH_TIMEOUT')).toBeUndefined() // not ours → upstream-cancel path + expect(timeoutOf(inner.signal)?.code).toBe('OUTER_TIMEOUT') // but IS a timeout, unscoped + }) }) diff --git a/packages/web/web-fetch-local/src/provider.ts b/packages/web/web-fetch-local/src/provider.ts index 53fc57f621..b15483ba38 100644 --- a/packages/web/web-fetch-local/src/provider.ts +++ b/packages/web/web-fetch-local/src/provider.ts @@ -249,13 +249,14 @@ function resolveRedirect(location: string, base: URL): URL { * Translate a thrown fetch/stream error into a `WebError`, classified by the * deadline signal rather than the error's shape (which differs by phase: the * request-phase `fetch` rejects with the abort reason, while the read-phase - * reader surfaces a bare `AbortError`). `timeoutOf(signal)` recovering a - * `TimeoutReason` means our timeout fired (`WEB_FETCH_TIMEOUT`); any other abort - * is upstream cancellation (`WEB_ABORTED`); a throw with the signal NOT aborted - * is a transport/network failure (`WEB_PROVIDER_ERROR`). + * reader surfaces a bare `AbortError`). `timeoutOf(signal, 'WEB_FETCH_TIMEOUT')` + * recovering OUR reason means our timeout fired (`WEB_FETCH_TIMEOUT`); any other + * abort — an upstream cancel, or a foreign/outer deadline's timeout under + * nesting — is `WEB_ABORTED`; a throw with the signal NOT aborted is a + * transport/network failure (`WEB_PROVIDER_ERROR`). */ function translateAbortOrNetwork(error: unknown, signal: AbortSignal): WebError { - const timeout = timeoutOf(signal) + const timeout = timeoutOf(signal, 'WEB_FETCH_TIMEOUT') if (timeout !== undefined) return new WebError('web fetch timed out', 'WEB_FETCH_TIMEOUT', { cause: timeout }) if (signal.aborted) return new WebError('web fetch aborted', 'WEB_ABORTED', { cause: error }) return new WebError(`web fetch failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error }) From 6beed9a883500fb7de88ca2e8ea5e38b021496bc Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Mon, 6 Jul 2026 19:55:46 +0800 Subject: [PATCH 021/119] test: make the timeout-wins race deterministic under fake timers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI (node 24/26) failed on the exact-boundary construction: advanceTimersByTime(100) then an immediate upstream.abort() let the manual abort win the race on some runtimes, so timeoutOf returned undefined. Advance unambiguously past the deadline and assert the timeout classification before firing the late abort — that late abort is now asserted as a no-op, which is the real first-cause-wins invariant. --- packages/util/timeout/tests/timeout.spec.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/util/timeout/tests/timeout.spec.ts b/packages/util/timeout/tests/timeout.spec.ts index 57066a4f54..588317f48d 100644 --- a/packages/util/timeout/tests/timeout.spec.ts +++ b/packages/util/timeout/tests/timeout.spec.ts @@ -99,7 +99,11 @@ describe('deadline — fuse with upstream', () => { try { const upstream = new AbortController() using d = deadline(upstream.signal, 100, 'WEB_FETCH_TIMEOUT') - vi.advanceTimersByTime(100) // timer fires first + vi.advanceTimersByTime(150) // past the 100ms deadline: the timer fires first + expect(d.signal.aborted).toBe(true) + expect(timeoutOf(d.signal)?.code).toBe('WEB_FETCH_TIMEOUT') + // A later upstream abort is a no-op on the already-aborted fused signal: + // AbortSignal.any keeps the FIRST cause, so the timeout classification stands. upstream.abort('too late') expect(timeoutOf(d.signal)?.code).toBe('WEB_FETCH_TIMEOUT') } finally { From e70227d5810a94af2ec084de35c91a6ac86bcf32 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:59:47 +0800 Subject: [PATCH 022/119] =?UTF-8?q?workflow:=20pin=20the=20spec=20engine's?= =?UTF-8?q?=20concurrency=20=E2=80=94=20the=20auto=20default=20is=20one=20?= =?UTF-8?q?slot=20on=20small=20CI=20runners?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two tests that wait for two children IN FLIGHT (the pipeline no-barrier test and the dropped-promise cancellation test) inherited the engine's auto-resolved maxConcurrentAgents, which is min(16, max(1, cores - 2)) — exactly 1 on the 2-core CI runner, so the second child never started and vi.waitFor timed out. Reproduced locally under taskset -c 0,1; the full spec passes there with the helper pinning a fixed ceiling. Tests about the ceiling itself keep their explicit overrides, and the auto-resolve arm stays covered by the default-config provider tests. --- packages/workflow/workflow-vm/tests/workflow-vm.spec.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index a4058303ea..ac037bdb04 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -97,7 +97,10 @@ async function setup(options?: SetupOptions) { options?.disposeDelayMs ?? 0, ) ctx.subagents.registerProvider(provider) - await ctx.plugin(VmWorkflowEngine, { provider: 'stub', ...options?.config }) + // A fixed concurrency ceiling: the auto-resolved default is machine-derived + // (cores - 2, floored at 1), so tests that expect N children in flight + // would wedge on small CI runners. Tests about the ceiling override it. + await ctx.plugin(VmWorkflowEngine, { provider: 'stub', maxConcurrentAgents: 8, ...options?.config }) return { ctx, provider, parent: fakeParent() } } From db4a39b02454f404c620e8efab06a9e469d4036f Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 21:02:41 +0800 Subject: [PATCH 023/119] workflow: close the review-found cancellation and child-lifecycle gaps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three review findings on the engine's child seam, one mechanism each: - Cancellation now bridges to run.cancel() on every in-flight child, not just the shared request signal — the subagent seam leaves a provider free to honor either channel, so the consumer drives both (listener removed in the child finally). - A child result REJECTION (an infrastructure fault the seam allows) now emits the paired workflow/agent-end before propagating, and propagates as a fatal WorkflowError with the new AGENT_RESULT code — previously it skipped agent-end (permanently open child for seq-matching observers) and dissolved to a per-item null inside parallel()/pipeline(), letting a broken provider read as an ordinary failed child. A rejection landing after cancel stays a cancellation (cancelled outcome + CANCELLED). - Every hook now guards its entry with a shared throwIfCancelled(): phase()/log() no longer emit observer events after a script caught an earlier cancelled rejection, and parallel()/pipeline() refuse entry — cancellation is the next HOOK boundary, not just the next agent(). --- docs/cordis-catalog/services.md | 2 +- packages/workflow/workflow-vm/src/runtime.ts | 53 +++++++-- .../workflow-vm/tests/workflow-vm.spec.ts | 102 +++++++++++++++++- packages/workflow/workflow/src/index.ts | 4 + 4 files changed, 148 insertions(+), 13 deletions(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index f1a61e2ecd..772a70f035 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -242,7 +242,7 @@ Semantics every implementation must honor: abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Source: [`packages/workflow/workflow/src/index.ts:194`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:198`](../../packages/workflow/workflow/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index b2a117fdcc..f1901ffaf7 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -17,10 +17,11 @@ * realm-side until they cross through a hook or the final return. * * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments, - * unsupported options/schemas, tripped caps, seam start failures, - * cancellation) ALWAYS propagate through `parallel`/`pipeline` — recognized - * by host `instanceof`, which a script cannot forge — and the per-item `null` - * is reserved for child-run failures and ordinary in-stage script errors. + * unsupported options/schemas, tripped caps, seam start failures and result + * rejections, cancellation) ALWAYS propagate through `parallel`/`pipeline` — + * recognized by host `instanceof`, which a script cannot forge — and the + * per-item `null` is reserved for child-run failures and ordinary in-stage + * script errors. * Every hook-returned promise gets a no-op rejection consumer attached, so a * script that drops a promise (fires an `agent()` without awaiting it) cannot * surface an unhandled rejection when cancellation rejects it — the app boot @@ -206,6 +207,17 @@ export class WorkflowExecution { return this.cancelReason !== undefined } + /** + * Shared hook entry guard: after {@link cancel}, EVERY hook throws + * `CANCELLED` at its next call — cancellation is the next HOOK boundary, + * not just the next `agent()`, so a script that caught one cancelled + * rejection cannot keep emitting progress through `phase`/`log` or enter a + * combinator. + */ + private throwIfCancelled(): void { + if (this.isCancelled()) throw this.cancelledError() + } + /** * Cancel the run: children abort (the shared signal), waiting `agent()` * slots reject, and every future hook call throws `CANCELLED` — the script @@ -358,7 +370,7 @@ export class WorkflowExecution { /** The `agent(prompt, opts)` hook. */ private async agent(rawPrompt: unknown, rawOpts: unknown): Promise { - if (this.isCancelled()) throw this.cancelledError() + this.throwIfCancelled() if (typeof rawPrompt !== 'string' || rawPrompt.length === 0) { throw new WorkflowError('agent() requires a non-empty prompt string', 'INVALID_ARGUMENT') } @@ -381,7 +393,7 @@ export class WorkflowExecution { // after its release — a cancel() landing in either window must not // start a child (it would carry an ALREADY-aborted signal, which a // provider subscribing only to future abort events would never see). - if (this.isCancelled()) throw this.cancelledError() + this.throwIfCancelled() let run try { run = this.ctx.subagents.start(this.limits.provider, { @@ -396,8 +408,30 @@ export class WorkflowExecution { } const info: WorkflowAgentInfo = { seq, label, ...phase !== undefined ? { phase } : {}, childId: run.id } this.observer.agentStart(info) + // Cancellation bridges to run.cancel() as well as the request signal: + // the seam leaves a provider free to honor either channel, so the + // consumer must drive both. The signal cannot be aborted yet (the block + // since the post-acquire check is synchronous), so the listener always + // arms; `once` plus the finally removal keep it leak-free. + const onAbort = (): void => { run.cancel(this.cancelReason) } + this.controller.signal.addEventListener('abort', onAbort, { once: true }) try { - const result = await run.result + let result + try { + result = await run.result + } catch (error: unknown) { + // The seam allows `result` to reject for an INFRASTRUCTURE fault — + // distinct from a child that failed and resolved. Pair the + // lifecycle before propagating, and propagate FATAL: an ordinary + // throw would dissolve to a per-item null inside the combinators, + // and a broken provider must not read as a failed child. + if (this.isCancelled()) { + this.observer.agentEnd({ ...info, outcome: 'cancelled' }) + throw this.cancelledError() + } + this.observer.agentEnd({ ...info, outcome: 'failed' }) + throw new WorkflowError(`child agent run failed: ${renderThrown(error)}`, 'AGENT_RESULT', { cause: error }) + } if (result.stopReason === 'completed') { if (opts.schema !== undefined) { // The provider honored outputSchema (capability-gated at start), so @@ -421,6 +455,7 @@ export class WorkflowExecution { this.observer.agentEnd({ ...info, outcome: 'failed' }) return null } finally { + this.controller.signal.removeEventListener('abort', onAbort) await run.dispose() } } finally { @@ -476,6 +511,7 @@ export class WorkflowExecution { /** The `parallel(thunks)` hook: each thunk caught → `null`; fatal errors propagate. */ private async parallel(rawThunks: unknown): Promise { + this.throwIfCancelled() if (!Array.isArray(rawThunks)) { throw new WorkflowError('parallel() requires an array of zero-argument functions', 'INVALID_ARGUMENT') } @@ -501,6 +537,7 @@ export class WorkflowExecution { /** The `pipeline(items, ...stages)` hook: per-item stage chains, NO cross-stage barrier. */ private async pipeline(rawItems: unknown, rawStages: unknown[]): Promise { + this.throwIfCancelled() if (!Array.isArray(rawItems)) { throw new WorkflowError('pipeline() requires an items array', 'INVALID_ARGUMENT') } @@ -542,6 +579,7 @@ export class WorkflowExecution { /** The `phase(title)` hook: sets the current label for subsequent `agent()` calls and notifies observers. */ private phase(title: unknown): void { + this.throwIfCancelled() if (typeof title !== 'string' || title.length === 0) { throw new WorkflowError('phase() requires a non-empty title string', 'INVALID_ARGUMENT') } @@ -551,6 +589,7 @@ export class WorkflowExecution { /** The `log(message)` hook: narration to observers. */ private log(message: unknown): void { + this.throwIfCancelled() if (typeof message !== 'string') { throw new WorkflowError('log() requires a message string', 'INVALID_ARGUMENT') } diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index ac037bdb04..1dc4833426 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -459,7 +459,7 @@ describe('dsh-workflow-vm', () => { expect((result.value as { message: string }).message).toContain('"bogus" is not recognized') }) - it('a non-WorkflowError host failure (a rejecting provider result) reaches the script raw', async () => { + it('a rejecting provider result is an infrastructure fault: fatal AGENT_RESULT, agent-end paired, no combinator dissolve', async () => { const ctx = new Context() await ctx.plugin(SubagentService) const provider: SubagentProvider = { @@ -475,11 +475,22 @@ describe('dsh-workflow-vm', () => { } ctx.subagents.registerProvider(provider) await ctx.plugin(VmWorkflowEngine, { provider: 'rejecting' }) - const result = await run(ctx, fakeParent(), script(` - try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, message: e.message } } + const ends: unknown[] = [] + ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) }) + // Direct await: the script reads the typed fields (a host object, so + // realm instanceof is false — same as every hook failure). + const direct = await run(ctx, fakeParent(), script(` + try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, code: e.code, fatal: e.fatal, message: e.message } } `)) - expect(result.value).toMatchObject({ name: 'Error' }) - expect((result.value as { message: string }).message).toContain('backend exploded') + expect(direct.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true }) + expect((direct.value as { message: string }).message).toContain('backend exploded') + // The child's lifecycle stays paired even though result never resolved. + expect(ends).toEqual([expect.objectContaining({ seq: 1, outcome: 'failed' })]) + // Through a combinator the fault PROPAGATES (fatal) — a broken provider + // must not dissolve into the per-item null and read as a failed child. + const throughParallel = await run(ctx, fakeParent(), script("return await parallel([() => agent('p')])")) + expect(throughParallel.stopReason).toBe('error') + expect(throughParallel.error).toContain('backend exploded') }) it('phase()/log() throw host WorkflowErrors synchronously on misuse', async () => { @@ -542,6 +553,87 @@ describe('dsh-workflow-vm', () => { await handle.dispose() }) + it('cancellation bridges to run.cancel() on every in-flight child, not just the request signal', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + script: script("return await parallel([() => agent('a'), () => agent('b')])"), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + handle.cancel('bridged') + expect((await handle.result).stopReason).toBe('cancelled') + // The seam leaves a provider free to honor run.cancel() rather than the + // request signal, so the engine must drive BOTH channels per child. + expect(provider.runs.map(r => r.cancelled)).toEqual(['bridged', 'bridged']) + await handle.dispose() + }) + + it('a provider whose result REJECTS on abort still gets a paired cancelled agent-end, and the run reports cancelled', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + // The seam allows result to reject for infrastructure faults; a backend + // that tears down uncleanly on abort exercises the rejection path WHILE + // the run is cancelled — which must stay a cancellation, not AGENT_RESULT. + const provider: SubagentProvider = { + name: 'reject-on-abort', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + inheritsParentContext: false, + start: request => ({ + id: AgentId('crashing-child'), + result: new Promise((_, reject) => { + request.signal?.addEventListener('abort', () => { reject(new Error('backend crashed on abort')) }, { once: true }) + }), + cancel: () => { /* the signal listener above is the teardown */ }, + dispose: () => Promise.resolve(), + }), + } + ctx.subagents.registerProvider(provider) + await ctx.plugin(VmWorkflowEngine, { provider: 'reject-on-abort' }) + const starts: unknown[] = [] + const ends: unknown[] = [] + ctx.on('workflow/agent-start', (_info, agent) => { starts.push(agent) }) + ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) }) + const handle = ctx.workflows.start({ script: script("return await agent('doomed')"), parent: fakeParent() }) + await vi.waitFor(() => { expect(starts.length).toBe(1) }) + handle.cancel('user aborted') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('user aborted') + expect(ends).toEqual([expect.objectContaining({ seq: 1, outcome: 'cancelled' })]) + await handle.dispose() + }) + + it('after cancellation EVERY hook throws at entry — phase/log/parallel/pipeline, not just agent()', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + let cancelled = false + const postCancel: string[] = [] + ctx.on('workflow/phase', (_info, title) => { if (cancelled) postCancel.push(`phase:${title}`) }) + ctx.on('workflow/log', (_info, message) => { if (cancelled) postCancel.push(`log:${message}`) }) + const handle = ctx.workflows.start({ + // The script survives each throw by catching, so every guarded hook is + // actually ATTEMPTED after the cancel; the run still reports cancelled. + script: script(` + phase('before') + try { await agent('x') } catch (e) {} + try { phase('after') } catch (e) {} + try { log('after') } catch (e) {} + try { await parallel([() => 'ran']) } catch (e) {} + try { await pipeline(['item'], p => p) } catch (e) {} + return 'survived by catching' + `), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + cancelled = true + handle.cancel('stop everything') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + // No post-cancel progress ever reached observers, and no child started. + expect(postCancel).toEqual([]) + expect(provider.runs.length).toBe(1) + await handle.dispose() + }) + it('an already-aborted request signal cancels before any child starts', async () => { const { ctx, parent, provider } = await setup({ manual: true }) const controller = new AbortController() diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 83b1560563..31b9eed038 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -127,6 +127,9 @@ export type WorkflowEventName = * subset (see dsh-tools). * - `AGENT_CAP` / `ITEM_CAP` — the run/agent caps tripped. * - `AGENT_START` — the subagent seam refused to start a child. + * - `AGENT_RESULT` — a child's `result` REJECTED: an infrastructure fault at + * the subagent seam, distinct from a child that failed and resolved (which + * is the per-item `null`, never an error). * - `RESULT_UNSERIALIZABLE` — a value crossing the script/host value boundary * is not plain JSON data. * - `CANCELLED` — the run was cancelled; pending and future hooks reject @@ -141,6 +144,7 @@ export type WorkflowErrorCode = | 'AGENT_CAP' | 'ITEM_CAP' | 'AGENT_START' + | 'AGENT_RESULT' | 'RESULT_UNSERIALIZABLE' | 'CANCELLED' From 3987425547eb302e176d86821cf8bc6d3ed5e094 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 21:03:40 +0800 Subject: [PATCH 024/119] subagent-inprocess: stop the structured nudge loop once cancellation lands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A cancel that lands AFTER a child's clean turn end but before the nudge continuation runs clears nothing — child.cancel() only kills queued or running work — so the loop's turn-state check alone let a later child.send() spend a fresh post-cancellation turn (and even capture a structured result the caller had already abandoned). The loop condition now also reads the run's own cancelled flag, re-evaluated after every whenIdle(), through an accessor because closure assignments are invisible to control-flow narrowing (an inline read lints always-true). readResult keeps the outcome honest on this path: a completed-but- uncaptured turn maps to aborted, not error, when a cancel is why the nudging stopped — the cancel contract outranks the schema shortfall. --- .../subagent/subagent-inprocess/src/index.ts | 24 ++++++++++++++----- .../tests/structured.spec.ts | 19 +++++++++++++++ 2 files changed, 37 insertions(+), 6 deletions(-) diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts index 93983e420c..381f94acba 100644 --- a/packages/subagent/subagent-inprocess/src/index.ts +++ b/packages/subagent/subagent-inprocess/src/index.ts @@ -171,6 +171,10 @@ export function startInProcessRun( // `turn/end` is logged — settles as `aborted` (honoring the cancel contract) // rather than falling through to the no-turn `error` mapping. let cancelled = false + // An accessor, not an inline read: `cancelled` mutates from closures (the + // abort listener, run.cancel), which control-flow narrowing cannot see — an + // inline `!cancelled` in the nudge condition reads as always-true. + const isCancelled = (): boolean => cancelled const requestCancel = (reason: string): void => { cancelled = true child.cancel(reason) @@ -191,12 +195,17 @@ export function startInProcessRun( // Nudge loop: a child that finished a turn CLEANLY without calling // structured_output gets re-prompted, up to the backend-configured // retry count. An errored/aborted turn is not nudged — its failure is - // the honest result. (This also covers a cancel: a cancelled turn ends - // `aborted`, and a pre-turn cancel leaves no `turn/end` at all, so - // neither reads `completed`.) + // the honest result (a cancelled turn ends `aborted`, and a pre-turn + // cancel leaves no `turn/end` at all, so neither reads `completed`). + // `!cancelled` closes the remaining window: a cancel landing AFTER a + // clean turn end clears nothing — `child.cancel()` only kills + // queued/running work — so without it the next `send` would spend a + // fresh post-cancellation turn; the condition re-evaluates after + // every `whenIdle()`, so a mid-nudge cancel stops the loop at the + // next boundary too. let nudges = options.structuredNudgeRetries while ( - structured.captured(child) === undefined && nudges > 0 + !isCancelled() && structured.captured(child) === undefined && nudges > 0 && lastOwnTurnEnd(child, seedLength)?.data.reason.kind === 'completed' ) { nudges -= 1 @@ -204,7 +213,7 @@ export function startInProcessRun( await child.whenIdle() } } - return readResult(child, seedLength, cancelled, structured ? { captured: structured.captured(child) } : undefined) + return readResult(child, seedLength, isCancelled(), structured ? { captured: structured.captured(child) } : undefined) } finally { request.signal?.removeEventListener('abort', onAbort) if (structured) { @@ -266,7 +275,10 @@ function readResult( : toStopReason(lastEnd?.data.reason) if (structured) { if (structured.captured) return { output, structured: structured.captured.value, stopReason } - if (stopReason === 'completed') return { output, stopReason: 'error' } + // No capture on a cleanly-completed turn: an ERROR when the run was left + // to finish (the nudges ran out), but ABORTED when a cancel is why the + // nudging stopped — the cancel contract outranks the schema shortfall. + if (stopReason === 'completed') return { output, stopReason: cancelled ? 'aborted' : 'error' } } return { output, stopReason } } diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts index be231f63e4..c8ca489451 100644 --- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts @@ -179,6 +179,25 @@ describe('in-process structured output', () => { await run.dispose() }) + it('a cancel landing after a clean turn end stops the nudge loop: no post-cancellation turn is spent', async () => { + const { ctx, parent, adapter } = await setup([textResponse('prose, no capture')], { nudges: 3 }) + const run = ctx.subagents.start('spawn', structuredRequest(parent)) + const child = ctx.agents.get(run.id)! + // Cancel synchronously inside the first turn's end recording — after the + // turn reads `completed`, before the nudge continuation resumes. The turn + // state alone cannot see this cancel (`child.cancel()` only clears + // queued/running work), so without the loop's own cancelled check the + // next send would spend a fresh child turn after the caller cancelled. + ctx.on('session/event', (session, event) => { + if (session === child.session && event.type === 'turn/end') run.cancel('cancelled between turn end and nudge') + }) + const result = await run.result + expect(result.stopReason).toBe('aborted') + // Exactly one model request: the nudge turn never ran. + expect(adapter.requests.length).toBe(1) + await run.dispose() + }) + it('rejects a schema outside the subset loud, before any child exists', async () => { const { ctx, parent } = await setup([]) expect(() => ctx.subagents.start('spawn', structuredRequest(parent, { From 9688870da31c74e77d0b34295e10bf468a9d4c6a Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 6 Jul 2026 21:04:20 +0800 Subject: [PATCH 025/119] =?UTF-8?q?docs(workflow):=20admit=20the=20node:vm?= =?UTF-8?q?=20escape=20concretely=20=E2=80=94=20absent=20globals=20are=20s?= =?UTF-8?q?urface,=20not=20containment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The review's critical finding: the engine README and the tool description read as if the missing filesystem/network/Node globals were enforced, but a script can reach the host Function constructor via globalThis.constructor.constructor and from it process and every Node builtin. Per the trust premise this is ACCEPTED (model-written scripts, bash-equivalent trust; genuine sandboxing is the deferred engine swap already listed) — but the docs must say so instead of implying a wall. The trust-premise sections (engine README, module doc, RFC) now name the escape and its acceptance; the model-facing tool description says the APIs are not PROVIDED rather than implying they are prevented. --- .../implemented/feature/2026-07-05-dynamic-workflows.md | 2 +- docs/tool-catalog/tools.md | 2 +- packages/workflow/tool-workflow/src/index.ts | 2 +- packages/workflow/workflow-vm/README.md | 4 ++-- packages/workflow/workflow-vm/src/index.ts | 9 ++++++--- 5 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 7d44ec91db..17c26760be 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -22,7 +22,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre ### The engine (dsh-workflow-vm): in-process node:vm -**Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) — host code MAY run script code while reading script values, and that is accepted, because a hostile script can already occupy the event loop forever with a synchronous spin past its first await; containing its error VALUES while conceding it the event loop would be cost without a threat model. Genuine hardening is an engine swap behind the seam (worker/isolated-vm gets value isolation by serialization for free), not incremental host-side defenses. +**Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) AND Node-API escape from the context — the vm context shares object machinery with the host, so a script can reach the host `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin; the absent globals are API surface, not containment. Host code MAY run script code while reading script values, and that is accepted, because a hostile script can already occupy the event loop forever with a synchronous spin past its first await; containing its error VALUES while conceding it the event loop would be cost without a threat model. Genuine hardening is an engine swap behind the seam (worker/isolated-vm gets value isolation by serialization for free), not incremental host-side defenses. **Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Under the trust premise, in-process is enough. Accepted, documented limitations: `start()` blocks the caller for the script's initial synchronous slice (bounded by the vm timeout); that timeout covers ONLY the initial slice, so a synchronous spin past it (an await continuation, a thenable's `then` invoked by promise resolution — a returned thenable resolves per JavaScript semantics, which is what makes an un-awaited `return agent('x')` work — or script code the host runs while rendering a thrown value) cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. diff --git a/docs/tool-catalog/tools.md b/docs/tool-catalog/tools.md index 76176dae86..b32c10e31f 100644 --- a/docs/tool-catalog/tools.md +++ b/docs/tool-catalog/tools.md @@ -293,7 +293,7 @@ Script-body hooks: Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. -Constraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. +Constraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. ```json { diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts index a116866887..4df4d6aba1 100644 --- a/packages/workflow/tool-workflow/src/index.ts +++ b/packages/workflow/tool-workflow/src/index.ts @@ -66,7 +66,7 @@ Script-body hooks: Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`. -Constraints: concurrency and total-agent caps apply; \`Date.now()\`, \`Math.random()\`, and argless \`new Date()\` throw (pass timestamps via \`args\`); no filesystem, network, timers, or Node.js APIs — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.` +Constraints: concurrency and total-agent caps apply; \`Date.now()\`, \`Math.random()\`, and argless \`new Date()\` throw (pass timestamps via \`args\`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.` type WorkflowCallArgs = { script: string; args?: Record } diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index 0ec1116cb7..e81e74dc7e 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -4,13 +4,13 @@ The first [`WorkflowService`](../workflow/README.md) implementation: an in-proce ## Trust premise -Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. vm is NOT a security boundary and no attempt is made to contain adversarial values: property reads on script values may run script code (a getter, a `toString`, a proxy trap) on the host stack, and a script determined to hang the process can simply spin past its first await (see the limitations below). What the engine DOES guarantee, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection (the app boot layer exits the process on those), values that JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing is an engine swap behind the seam (worker-thread/isolated-vm, where the boundary is serialization by construction), not incremental host-side defenses here. +Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. vm is NOT a security boundary and no attempt is made to contain adversarial values: property reads on script values may run script code (a getter, a `toString`, a proxy trap) on the host stack, and a script determined to hang the process can simply spin past its first await (see the limitations below). Concretely, the context is **escapable by construction**: `node:vm` shares object machinery with the host, so a script can reach the host `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin — the absent globals and determinism bans are API surface that keeps honest scripts portable and resume-compatible, not walls. What the engine DOES guarantee, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection (the app boot layer exits the process on those), values that JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing is an engine swap behind the seam (worker-thread/isolated-vm, where the boundary is serialization by construction), not incremental host-side defenses here. ## The script contract it executes - **Meta extraction** (`extractMeta`): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. - **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline). -- **Determinism bans**: `Date.now()`, `Math.random()`, and argless `new Date()` throw (kept even though resume is deferred, so scripts stay resume-compatible); no timers, filesystem, or Node APIs exist in the context. +- **Determinism bans**: `Date.now()`, `Math.random()`, and argless `new Date()` throw (kept even though resume is deferred, so scripts stay resume-compatible); no timers, filesystem, or Node APIs are injected into the context (absence is API surface, not containment — see the trust premise). ## The value boundary diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-vm/src/index.ts index 9b8c646aa9..c1300427a2 100644 --- a/packages/workflow/workflow-vm/src/index.ts +++ b/packages/workflow/workflow-vm/src/index.ts @@ -7,9 +7,12 @@ * TRUST PREMISE: scripts are MODEL-WRITTEN — the same trust level as the * model's existing bash access — so this engine defends against BUGGY * scripts, never hostile ones. vm is NOT a security boundary and no attempt - * is made to contain adversarial values (see ./realm.ts); genuine sandboxing - * is an engine swap behind the seam (worker-thread/isolated-vm), not - * incremental host-side defenses here. + * is made to contain adversarial values (see ./realm.ts); the context is + * escapable by construction (the host `Function` constructor is reachable via + * `globalThis.constructor.constructor`, and `process` from there), so the + * absent globals are API surface, not containment. Genuine sandboxing is an + * engine swap behind the seam (worker-thread/isolated-vm), not incremental + * host-side defenses here. * * Engine limitations, documented as the accepted cost of the in-process * mechanism: From 4641f1a851b4579adb3cd7ccd50ba53b4102ce04 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 7 Jul 2026 09:26:47 +0800 Subject: [PATCH 026/119] chore: absorb the no-nudge seam into the workflow tree The parent branch dropped structuredNudgeRetries; the two workflow-side test setups stop passing it, and the RFC's foundation paragraph now describes the current design (final-ASSEMBLY enforcement logged via request/header, the post-capture pre-execute deny, the start() schema snapshot, no re-prompt) instead of the retired agent/request + nudge shape. --- docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md | 2 +- packages/workflow/workflow-vm/tests/integration.spec.ts | 2 +- packages/workflow/workflow-vm/tests/workflow.e2e.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 17c26760be..7bf09f742c 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -36,7 +36,7 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai ### The foundation: structured output on the subagent seam -`agent({schema})` needs `SubagentStartRequest.outputSchema` to actually work; it was vocabulary without an implementation (`outputSchema: false` everywhere). Implemented in `dsh-subagent-inprocess` for both in-process backends: a globally registered `structured_output` capture tool whose per-child schema is enforced by a `prepend: true` `agent/request` listener doing FINAL-REQUEST enforcement (post-processing `await next()` — cooperative mutation would not survive a downstream listener returning a replacement request; the listener also appends the calling instruction to the request's `system` text, since `AgentOptions` carries no per-agent prompt field), a `prepend: true` `agent/turn-continuation` veto after capture (no wasted extra model step, and an earlier-registered force-continue listener cannot short-circuit it), validation-retry in-turn via `ToolArgsError`, and a clean-finish nudge loop (`structuredNudgeRetries`). Lifetime is refcounted by backends (plugin lifetime) AND live runs (start → settle). The seam's `outputSchema` type became the raw JSON-Schema SUBSET (`StructuredOutputSchema` in dsh-tools: single-string `type`, `properties`/`required`/`additionalProperties`, `items`, scalar `enum`/`const`; anything unenforced is rejected loud) — the schema travels verbatim to the model as the forced tool's parameters, so the wire format, not the author DSL, is the right vocabulary. +`agent({schema})` needs `SubagentStartRequest.outputSchema` to actually work; it was vocabulary without an implementation (`outputSchema: false` everywhere). Implemented in `dsh-subagent-inprocess` for both in-process backends: a globally registered `structured_output` capture tool whose per-child schema is enforced by a `prepend: true` `system-prompt/assemble` listener doing FINAL-ASSEMBLY enforcement (post-processing `await next()` — cooperative mutation would not survive a downstream listener returning a replacement assembly; the calling instruction rides as a trailing prompt section, since `AgentOptions` carries no per-agent prompt field, and the loop logs the result as the step's `request/header`, keeping the injection reconstructable), a `prepend: true` `agent/turn-continuation` veto after capture (no wasted extra model step) plus a `tools/pre-execute` deny for calls arriving after the capture (terminal within the step, not only at its end), and validation-retry in-turn via `ToolArgsError`. The schema is `structuredClone`d at `start()` (caller mutation cannot drift enforcement). Deliberately NO re-prompt: a child that finishes cleanly without calling the tool settles `error` to the parent. Lifetime is refcounted by backends (plugin lifetime) AND live runs (start → settle). The seam's `outputSchema` type became the raw JSON-Schema SUBSET (`StructuredOutputSchema` in dsh-tools: single-string `type`, `properties`/`required`/`additionalProperties`, `items`, scalar `enum`/`const`; anything unenforced is rejected loud) — the schema travels verbatim to the model as the forced tool's parameters, so the wire format, not the author DSL, is the right vocabulary. ## Deferred (documented non-goals of this cut) diff --git a/packages/workflow/workflow-vm/tests/integration.spec.ts b/packages/workflow/workflow-vm/tests/integration.spec.ts index 48b308a986..3572131a8a 100644 --- a/packages/workflow/workflow-vm/tests/integration.spec.ts +++ b/packages/workflow/workflow-vm/tests/integration.spec.ts @@ -32,7 +32,7 @@ async function setup(script: Script) { await ctx.plugin(Invariants) await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SubagentService) - await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) + await ctx.plugin(spawn, { providerName: 'spawn' }) await ctx.plugin(VmWorkflowEngine, {}) ctx.llm.registerAdapter(['mock'], adapter) const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) diff --git a/packages/workflow/workflow-vm/tests/workflow.e2e.ts b/packages/workflow/workflow-vm/tests/workflow.e2e.ts index 6ddfdb7251..c3f959d072 100644 --- a/packages/workflow/workflow-vm/tests/workflow.e2e.ts +++ b/packages/workflow/workflow-vm/tests/workflow.e2e.ts @@ -39,7 +39,7 @@ async function harness(): Promise { await built.plugin(AgentLoop, { agents: [] }) await built.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] }) await built.plugin(SubagentService) - await built.plugin(Spawn, { providerName: 'spawn', structuredNudgeRetries: 1 }) + await built.plugin(Spawn, { providerName: 'spawn' }) await built.plugin(VmWorkflowEngine, { provider: 'spawn' }) await built.plugin(ToolWorkflow, {}) return built From cebf781d69c774348aac90747e29fb5fa2796bb4 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 7 Jul 2026 14:57:06 +0800 Subject: [PATCH 027/119] fix review findings: polish ask-user question --- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/user-interaction.md | 50 ++-- .../feature/2026-06-25-ask-user-question.md | 12 +- docs/tool-catalog/tools.md | 59 ++-- .../tests/snapshots/cancel/session.jsonl | 2 +- .../snapshots/error-finish/session.jsonl | 2 +- .../tests/snapshots/fs-edit/session.jsonl | 2 +- .../snapshots/fs-policy-reject/session.jsonl | 2 +- .../snapshots/fs-read-window/session.jsonl | 2 +- .../tests/snapshots/fs-read/session.jsonl | 2 +- .../snapshots/fs-terminal-card/session.jsonl | 2 +- .../fs-write-overwrite/session.jsonl | 2 +- .../tests/snapshots/fs-write/session.jsonl | 2 +- .../hook-cc-posttool-block/session.jsonl | 2 +- .../hook-cc-posttool-context/session.jsonl | 2 +- .../hook-cc-pretool-ask/session.jsonl | 2 +- .../hook-cc-pretool-deny/session.jsonl | 2 +- .../session.jsonl | 2 +- .../hook-cc-stop-continue/session.jsonl | 2 +- .../hook-codex-posttool-block/session.jsonl | 2 +- .../hook-codex-posttool-context/session.jsonl | 2 +- .../hook-codex-pretool-block/session.jsonl | 2 +- .../session.jsonl | 2 +- .../hook-codex-stop-continue/session.jsonl | 2 +- .../tests/snapshots/multi-turn/session.jsonl | 2 +- .../snapshots/subagent-fork/session.1.jsonl | 4 +- .../snapshots/subagent-fork/session.jsonl | 2 +- .../snapshots/subagent-mixed/session.1.jsonl | 2 +- .../snapshots/subagent-mixed/session.2.jsonl | 4 +- .../snapshots/subagent-mixed/session.jsonl | 2 +- .../snapshots/subagent-multi/session.1.jsonl | 2 +- .../snapshots/subagent-multi/session.2.jsonl | 2 +- .../snapshots/subagent-multi/session.jsonl | 2 +- .../snapshots/subagent-spawn/session.1.jsonl | 2 +- .../snapshots/subagent-spawn/session.jsonl | 2 +- .../tests/snapshots/text-turn/session.jsonl | 2 +- .../tests/snapshots/todo-plan/session.jsonl | 2 +- .../snapshots/tool-call-turn/session.jsonl | 2 +- .../snapshots/workspace-edit/session.jsonl | 2 +- packages/core/user-interaction/README.md | 10 +- packages/core/user-interaction/src/index.ts | 41 ++- .../tests/user-interaction.spec.ts | 27 +- packages/ui/acp/README.md | 2 +- packages/ui/acp/src/index.ts | 118 ++++---- packages/ui/acp/tests/bridge.spec.ts | 104 ++++--- packages/ui/stdio-agent/src/stdio-chat.ts | 96 ++++--- .../ui/stdio-agent/tests/stdio-chat.spec.ts | 271 ++++++++++++------ packages/ui/tool-ask-user/README.md | 10 +- packages/ui/tool-ask-user/src/index.ts | 60 ++-- .../tool-ask-user/tests/tool-ask-user.spec.ts | 146 ++++++---- scripts/type-equiv.manifest.json | 2 + 51 files changed, 665 insertions(+), 419 deletions(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 3def20ac2f..fea8840513 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -215,7 +215,7 @@ registerProvider(provider: UserInteractionProvider): () => void async ask(request: AskUserQuestionRequest): Promise ``` -Source: [`packages/core/user-interaction/src/index.ts:70`](../../packages/core/user-interaction/src/index.ts) +Source: [`packages/core/user-interaction/src/index.ts:82`](../../packages/core/user-interaction/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md index b0c5f5145c..1f8d135a51 100644 --- a/docs/core-data-structures/user-interaction.md +++ b/docs/core-data-structures/user-interaction.md @@ -6,35 +6,44 @@ Source: [`packages/core/user-interaction/src/index.ts`](../../packages/core/user ## Question options -`AskUserQuestionOption` is the selectable-choice shape. `label` is user-facing, while `value` is the model-facing answer returned when the option is selected; when omitted, providers use the label. +`AskUserQuestionOption` is the selectable-choice shape. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text. ```ts type-equiv interface AskUserQuestionOption { /** User-facing label. */ label: string - /** Value returned to the model when selected. Defaults to `label`. */ - value?: string /** Optional extra context rendered by capable UIs. */ description?: string - /** Marks the recommended/default option. */ - recommended?: boolean } ``` -## Ask request +## Question item -`AskUserQuestionRequest` is the cross-package request. `options` being absent means free-form input; an optionless request remains free-form even when a caller sets `allowCustom: false`, because there is no selectable option to constrain the answer to. +`AskUserQuestionItem` is one question in a request. The model supplies a stable `id`, which is echoed back with the answer so batched questions remain routable. ```ts type-equiv -interface AskUserQuestionRequest { +interface AskUserQuestionItem { + /** Stable model-provided question id, echoed in the answer. */ + id: string /** The question to display. */ question: string /** Optional short heading/group label. */ header?: string /** Optional choices the UI can render as a menu. */ options?: AskUserQuestionOption[] - /** Whether free-form answers are accepted. Defaults to `true`. */ - allowCustom?: boolean + /** Whether more than one option may be selected. Defaults to single-select. */ + multiSelect?: boolean +} +``` + +## Ask request + +`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer. + +```ts type-equiv +interface AskUserQuestionRequest { + /** Questions to display. */ + questions: AskUserQuestionItem[] /** Calling agent, when the request came from an agent tool call. */ agent?: Agent /** Abort signal for the owning tool/step. */ @@ -44,14 +53,23 @@ interface AskUserQuestionRequest { ## Answer -Providers return the model-facing `answer` text and optionally echo the chosen option as metadata. Consumers should use `answer`; the option is for UI/session metadata and diagnostics. +Providers return one answer per answered question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. When `custom` is present, `selected` is empty; custom text is an answer override, not a supplement to selected choices. + +```ts type-equiv +interface AskUserQuestionAnswerItem { + /** The answered question id. */ + id: string + /** Selected option labels. Empty when the answer is purely custom text. */ + selected: string[] + /** Optional free-text "Other" answer. */ + custom?: string +} +``` ```ts type-equiv interface AskUserQuestionAnswer { - /** Model-facing answer text. */ - answer: string - /** The selected option, when the answer came from `options`. */ - option?: AskUserQuestionOption + /** Structured answers keyed by question id. */ + answers: AskUserQuestionAnswerItem[] } ``` @@ -67,7 +85,7 @@ interface UserInteractionProvider { ## Errors -`UserInteractionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `NO_PROVIDER`, `ASK_ABORTED`, or ACP-side cancellation. +`UserInteractionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `ASK_ABORTED`, or ACP-side cancellation. ```ts type-equiv class UserInteractionError extends HarnessError { diff --git a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md index aa78fbc275..04d183aa9c 100644 --- a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md +++ b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md @@ -10,19 +10,19 @@ This is a user-facing capability, but it also crosses package boundaries. A mode ## Decision -Introduce `dsh-user-interaction` as the core interface package for `ctx.userInteraction`, and keep the model-facing consumer `dsh-tool-ask-user` under `packages/ui/tool-ask-user` rather than the core spine. The split is intentional: core owns the abstract seam and stable request/answer/error vocabulary; UI product surfaces own the affordance that asks a human and the concrete provider that collects the answer. The tool registers `ask_user_question`, forwards `{ question, header, options, allowCustom, agent, signal }`, and returns the provider-computed `answer` as the tool result. +Introduce `dsh-user-interaction` as the core interface package for `ctx.userInteraction`, and keep the model-facing consumer `dsh-tool-ask-user` under `packages/ui/tool-ask-user` rather than the core spine. The split is intentional: core owns the abstract seam and stable request/answer/error vocabulary; UI product surfaces own the affordance that asks a human and the concrete provider that collects the answer. The tool registers `ask_user_question`, forwards `{ questions, agent, signal }`, and returns the provider-computed structured answers as the tool result. -The request vocabulary supports a short `header`, the required `question`, optional mutually exclusive `options`, `description` for each option, a `recommended` marker, and `allowCustom`. `label` is user-facing display text; `value` is the model-facing answer for a selected option and defaults to `label`. Providers return `AskUserQuestionAnswer.answer` as the single source of truth; the selected `option` is metadata. The tool schema exposes `description` only, not the synonym `desc`, to keep the model-facing surface small. +The model-facing request vocabulary is deliberately aligned with the product-research schema: `ask_user_question({ questions: [{ id, question, header?, options?: [{ label, description? }], multi_select? }] })`. `id` is supplied per question and echoed in the result so a batch can be routed without relying on question text. `label` is both user-facing display text and the selected value returned to the model; there is no separate `value`, no `recommended`, no `allow_custom`, and no `desc` alias. -Optionless questions are always free-form, even if a caller passes `allowCustom: false`. The opposite would create an unanswerable prompt: with no option to select and free-form input disallowed, every human answer would be rejected forever. Providers therefore treat "no options" as the free-form shape. +Providers return `{ answers: [{ id, selected, custom? }] }`. `selected` is always an array of selected option labels, so single-select and `multi_select` answers share one result shape. `custom` carries a free-text "Other" answer; optionless questions collect `custom` directly. When `custom` is present, it overrides any selected choices and `selected` is empty. `UserInteractionError` extends `HarnessError`, so failures such as `NO_PROVIDER`, `ASK_ABORTED`, ACP cancellation, or missing session routing survive `ctx.tools.execute()` as machine-routable `{ name, code }` tool errors. This matches the structured-error taxonomy and lets the model or a wrapping plugin distinguish "user cancelled" from a generic thrown exception. ## UI mappings -`dsh-stdio-agent`'s in-package readline module renders the question, sorts recommended options first, shows each option's `description` on the next line, accepts the recommended option on an empty answer, and rejects pending questions on abort, provider disposal, or stdin EOF. The stdio provider serializes multiple simultaneous questions with an internal queue so only one prompt owns stdin at a time. +`dsh-stdio-agent`'s in-package readline module renders each question, shows each option's `description` on the next line, supports comma/space-separated numeric choices for `multi_select`, accepts free-form custom answers, and rejects pending questions on abort, provider disposal, or stdin EOF. A batched request is asked in order and resolved as one answer object. The stdio provider serializes simultaneous requests with an internal queue so only one prompt owns stdin at a time. -`dsh-acp` provides the same seam for ACP sessions. It routes an ask request from the calling `Agent` through the bridge's `agent→sessionId` reverse map and calls ACP `unstable_createElicitation` with a session-scoped form. Option choices become a `choice` single-select field with the recommended option as the schema default; free-form answers use `answer` for optionless questions and `custom_answer` when options plus custom input are allowed. ACP `decline`/`cancel`, a missing answer, a missing session, and a client without elicitation support all become structured `UserInteractionError`s. +`dsh-acp` provides the same seam for ACP sessions. It routes an ask request from the calling `Agent` through the bridge's `agent→sessionId` reverse map and calls ACP `unstable_createElicitation` with a session-scoped form for each question. Single-select options become a `choice` string enum; `multi_select` options become a `choice` array enum; optionless questions use a required `custom` text field. If the client returns both `choice` and non-empty `custom`, the custom answer wins. ACP `decline`/`cancel`, a missing answer, a missing session, and a client without elicitation support all become structured `UserInteractionError`s. The ACP mapping deliberately uses elicitation, not `session/request_permission`. `request_permission` is still reserved for the separate permission gate: it is a yes/no-or-policy authorization protocol around tool execution. `ask_user_question` is a general information-gathering tool with optional free-form answers, so ACP form elicitation is the closer protocol fit. The bridge's session routing is shared with the future permission gate, but the user intent is different. @@ -46,4 +46,4 @@ The feature gives the model a powerful pause primitive, so prompt guidance matte ## Testing -Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, structured tool errors through `ctx.tools.execute()`, option labels/values, and the model schema including the removal of `desc`. `dsh-stdio-agent` tests cover recommended-first display, descriptions, queued questions, EOF/abort cleanup, and optionless free-form input even with `allowCustom: false`. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify both selected-option and optionless free-form elicitation paths continue the agent loop. +Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. `dsh-stdio-agent` tests cover option descriptions, queued requests, EOF/abort cleanup, optionless free-form input, invalid option reprompts, duplicate multi-select numbers, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop. diff --git a/docs/tool-catalog/tools.md b/docs/tool-catalog/tools.md index 3ec06fd1bb..6b65aaf4cd 100644 --- a/docs/tool-catalog/tools.md +++ b/docs/tool-catalog/tools.md @@ -26,55 +26,64 @@ This table connects model-visible tool names to the plugin package and service s ### `ask_user_question` -Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest. +Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer. ```json { "type": "object", "properties": { - "header": { - "type": "string", - "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"." - }, - "question": { - "type": "string", - "description": "The specific question to ask the user." - }, - "options": { + "questions": { "type": "array", - "description": "Optional mutually exclusive choices to show the user.", + "description": "Questions to ask the user before continuing.", "items": { "type": "object", "properties": { - "label": { + "id": { "type": "string", - "description": "Short user-facing option label." + "description": "Stable id for this question; echoed in the answer." }, - "value": { + "question": { "type": "string", - "description": "Answer text returned to you if this option is selected. Defaults to label." + "description": "The specific question to ask the user." }, - "description": { + "header": { "type": "string", - "description": "One sentence explaining the tradeoff or impact." + "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"." }, - "recommended": { + "options": { + "type": "array", + "description": "Optional choices to show the user.", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Short user-facing option label." + }, + "description": { + "type": "string", + "description": "One sentence explaining the tradeoff or impact." + } + }, + "required": [ + "label" + ] + } + }, + "multi_select": { "type": "boolean", - "description": "True for the recommended/default option." + "description": "Whether the user may select more than one option. Defaults to false." } }, "required": [ - "label" + "id", + "question" ] } - }, - "allow_custom": { - "type": "boolean", - "description": "Whether the user may type a free-form answer instead of selecting an option. Defaults to true." } }, "required": [ - "question" + "questions" ] } ``` diff --git a/examples/acp-agent/tests/snapshots/cancel/session.jsonl b/examples/acp-agent/tests/snapshots/cancel/session.jsonl index 58e4ffb8b7..5f80f5a214 100644 --- a/examples/acp-agent/tests/snapshots/cancel/session.jsonl +++ b/examples/acp-agent/tests/snapshots/cancel/session.jsonl @@ -2,7 +2,7 @@ {"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":"Start a long task; this turn will be cancelled mid-stream."}],"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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"partial"}}} {"type":"step/end","seq":6,"time":0,"data":{"turn":1,"step":1}} diff --git a/examples/acp-agent/tests/snapshots/error-finish/session.jsonl b/examples/acp-agent/tests/snapshots/error-finish/session.jsonl index 6d400a53d1..aecc1b0b7b 100644 --- a/examples/acp-agent/tests/snapshots/error-finish/session.jsonl +++ b/examples/acp-agent/tests/snapshots/error-finish/session.jsonl @@ -2,6 +2,6 @@ {"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":"This prompt triggers a recorded provider error."}],"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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"step/end","seq":4,"time":0,"data":{"turn":1,"step":1}} {"type":"turn/end","seq":5,"time":0,"data":{"turn":1,"reason":{"kind":"error","step":1,"message":"simulated provider error (HTTP 401)","code":"AUTH"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl b/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl index 37bfe01833..7eea57d216 100644 --- a/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-edit/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279365277,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279365278,"data":{"content":[{"type":"text","text":"First use the read tool to read config.txt in the current directory. Then use the edit tool (NOT bash) to replace the literal text DEBUG with RELEASE in that file. Then reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279365279,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279365279,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-0g5rlt.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279365279,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-0g5rlt.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279365884,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279365884,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} {"type":"assistant/chunk","seq":6,"time":1783279365982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl b/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl index 842d0e2777..505cd707d3 100644 --- a/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279382954,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279382954,"data":{"content":[{"type":"text","text":"Do NOT use the read tool. Immediately use the edit tool to replace the literal text blue with green in settings.txt in the current directory. Do not read the file first. After the tool result, reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279382955,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279382956,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-qgXmIP.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279382956,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-qgXmIP.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279383606,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279383606,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279383721,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl b/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl index 9a00ad40ca..92c11d97c0 100644 --- a/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279377803,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279377804,"data":{"content":[{"type":"text","text":"Use the read tool (NOT bash) with offset 5 and limit 4 to read lines 5 through 8 of big.txt in the current directory. Then reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279377806,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279377806,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-mA31X1.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279377806,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-mA31X1.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279378450,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279378450,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279378533,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-read/session.jsonl b/examples/acp-agent/tests/snapshots/fs-read/session.jsonl index 85fd577e87..db294acf6c 100644 --- a/examples/acp-agent/tests/snapshots/fs-read/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-read/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279355670,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279355671,"data":{"content":[{"type":"text","text":"Use the read tool (NOT bash) to read the file greeting.txt in the current directory, then reply with exactly the single word DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279355673,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279355673,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-Zo3aiO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279355673,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-Zo3aiO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279356329,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279356330,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279356465,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl b/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl index d9fac13ea8..66f8602f66 100644 --- a/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279337866,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279337867,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279337868,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279337871,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-ImzwJW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279337871,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-ImzwJW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279338459,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279338459,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279338579,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl b/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl index fdf94ea612..de95e9a6be 100644 --- a/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl @@ -2,7 +2,7 @@ {"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":"First use the read tool to read data.txt in the current directory. Then use the write tool (NOT bash) to replace its entire contents with exactly the single line: replaced. Then reply with exactly the single word 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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-write/session.jsonl b/examples/acp-agent/tests/snapshots/fs-write/session.jsonl index abef504690..2556786c95 100644 --- a/examples/acp-agent/tests/snapshots/fs-write/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-write/session.jsonl @@ -2,7 +2,7 @@ {"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 write tool (NOT bash) to create a file named notes.txt in the current directory containing exactly the single line: hello world. Then reply with exactly the single word 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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl index 4ac44af230..09f79121b1 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279438851,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279438852,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279438853,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279438856,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-4FNHMZ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279438856,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-4FNHMZ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279439575,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279439576,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279439723,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl index b8235b52b5..63a2824be4 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279454673,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279454674,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279454675,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279454676,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-l0uhay.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279454676,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-l0uhay.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279455097,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279455097,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279455192,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl index fffda139e8..09cd1689aa 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279433755,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279433756,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279433757,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279433759,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-GbznxQ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279433759,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-GbznxQ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279434229,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279434229,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279434325,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl index a2a735ffdc..75803fb92b 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279428483,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279428484,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279428485,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279428488,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YXKW6X.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279428488,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YXKW6X.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279429149,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279429149,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279429278,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl index 53f6cbf940..9594344c21 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl @@ -5,7 +5,7 @@ {"type":"user/message","seq":3,"time":1783279424786,"data":{"content":[{"type":"text","text":"What is my favorite color? Reply with just the color and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"context/message","seq":4,"time":1783279424786,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-claude"}},"surfaceOp":"append"} {"type":"step/start","seq":5,"time":1783279424787,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":6,"time":1783279424788,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-jHjRG4.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":6,"time":1783279424788,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-jHjRG4.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":7,"time":1783279425470,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":8,"time":1783279425471,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":9,"time":1783279425619,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl index 929409df1e..b98063b1f8 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279459589,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279459590,"data":{"content":[{"type":"text","text":"Reply with the single word FIRST and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279459591,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279459592,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-y7ZIlD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279459592,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-y7ZIlD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279460023,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279460023,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279460120,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl index 3e50292d5d..44dcb25682 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279472951,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279472952,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279472953,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279472957,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-up4xkk.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279472957,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-up4xkk.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279473683,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279473683,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279473835,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl index dc8e1fe918..746769acbb 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279478902,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279478903,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279478904,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279478905,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-S4Pl3Q.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279478905,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-S4Pl3Q.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279479573,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279479573,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279479735,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl index bc84fb16ac..bc71251497 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279467545,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279467546,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo HELLO. Report the tool result you got back verbatim, then stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279467547,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279467548,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XJzzAW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279467548,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XJzzAW.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279468248,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279468248,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279468448,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl index d0dc0b550c..bf9cb5f2aa 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl @@ -5,7 +5,7 @@ {"type":"user/message","seq":3,"time":1783279463864,"data":{"content":[{"type":"text","text":"What is my favorite color? Reply with just the color and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"context/message","seq":4,"time":1783279463864,"data":{"content":[{"type":"text","text":"The user has previously stated their favorite color is teal."}],"source":{"kind":"plugin","plugin":"hooks-codex"}},"surfaceOp":"append"} {"type":"step/start","seq":5,"time":1783279463865,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":6,"time":1783279463866,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-dXMGno.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":6,"time":1783279463866,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-dXMGno.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":7,"time":1783279464538,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":8,"time":1783279464539,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":9,"time":1783279464680,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl b/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl index bd7f21b30b..f30cbb0413 100644 --- a/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279484315,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279484316,"data":{"content":[{"type":"text","text":"Reply with the single word FIRST and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279484317,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279484319,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-CW2Kzh.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279484319,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-CW2Kzh.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279484964,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279484964,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279485118,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl b/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl index d1488562b9..82fd83c799 100644 --- a/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/multi-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279390951,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279390951,"data":{"content":[{"type":"text","text":"Reply with exactly the word: ONE. No tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279390953,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279390953,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YRz0cJ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279390953,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-YRz0cJ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279391532,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279391532,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279391637,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl index b9df18dad9..41f1470806 100644 --- a/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279408071,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279408071,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is MARMALADE. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279408072,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279408906,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} @@ -35,7 +35,7 @@ {"type":"turn/start","seq":33,"time":1783279410879,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":34,"time":1783279410880,"data":{"content":[{"type":"text","text":"What is the project codeword mentioned earlier in this conversation? Reply with exactly that one word and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":35,"time":1783279410880,"data":{"turn":2,"step":1}} -{"type":"request/header","seq":36,"time":1783279410880,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} +{"type":"request/header","seq":36,"time":1783279410880,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} {"type":"assistant/chunk","seq":37,"time":1783279411585,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":38,"time":1783279411586,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":39,"time":1783279411711,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl index e21dba852b..5da19c9516 100644 --- a/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279408071,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279408071,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is MARMALADE. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279408072,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279408073,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yKv3Ie.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279408758,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279408906,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl index 7f426c7e0f..4480b90e56 100644 --- a/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279418198,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279418198,"data":{"content":[{"type":"text","text":"Reply with exactly the word ALPHA and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279418198,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279418198,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279418198,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279418756,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279418756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279418937,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl index eec185bfd7..99762f7b80 100644 --- a/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279415444,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279415445,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is SAFFRON. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279415446,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279416310,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} @@ -29,7 +29,7 @@ {"type":"turn/start","seq":27,"time":1783279420404,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":28,"time":1783279420404,"data":{"content":[{"type":"text","text":"What is the project codeword mentioned earlier in this conversation? Reply with exactly that one word and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":29,"time":1783279420405,"data":{"turn":2,"step":1}} -{"type":"request/header","seq":30,"time":1783279420405,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} +{"type":"request/header","seq":30,"time":1783279420405,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"resume"}} {"type":"assistant/chunk","seq":31,"time":1783279421097,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":32,"time":1783279421098,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":33,"time":1783279421204,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl index 9d6fe663cd..5c4e1350e7 100644 --- a/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279415444,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279415445,"data":{"content":[{"type":"text","text":"Remember this fact for later: the project codeword is SAFFRON. Reply with the single word OK and stop. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279415446,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279415446,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-h3RUf6.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279416146,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279416310,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl index d650e3f381..c476b1ef9f 100644 --- a/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279402204,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279402204,"data":{"content":[{"type":"text","text":"Reply with exactly the word ALPHA and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279402205,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279402205,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279402205,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279402608,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279402608,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279402723,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl index 6e37fa2ad6..79c29ab258 100644 --- a/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279403730,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279403730,"data":{"content":[{"type":"text","text":"Reply with exactly the word BETA and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279403730,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279403730,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279403730,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279404370,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279404370,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279404532,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl index 0960b62547..5477534fca 100644 --- a/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279400642,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279400642,"data":{"content":[{"type":"text","text":"Use the subagent tool TWICE, once at a time, to delegate two subtasks to child agents. First subtask: 'Reply with exactly the word ALPHA and nothing else.' Second subtask (after the first returns): 'Reply with exactly the word BETA and nothing else.' After both subagents return, reply with the single word PARENT_DONE and stop. Do not use the bash tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279400643,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279400646,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279400646,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-tIoYon.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279401312,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279401312,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279401437,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl index c38e6d2988..183214fa62 100644 --- a/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279396597,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279396597,"data":{"content":[{"type":"text","text":"Reply with exactly the word CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279396598,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279396598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279396598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279397154,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279397154,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279397252,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl index f0bc7d96f2..31d93e40a6 100644 --- a/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279395301,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279395302,"data":{"content":[{"type":"text","text":"Use the subagent tool exactly once to delegate this subtask to a child agent: 'Reply with exactly the word CHILD_OK and nothing else.' After the subagent returns, reply with the single word PARENT_DONE and stop. Do not use the bash tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279395303,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279395304,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279395304,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JrLIIO.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279395862,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279395862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279395973,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index 539747bd0c..6d2783b6cb 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279329596,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279329596,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279329598,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279330154,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl b/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl index 5e4e8db328..4238bf797a 100644 --- a/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl +++ b/examples/acp-agent/tests/snapshots/todo-plan/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279342895,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279342896,"data":{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279342897,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279342898,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-t9J1QD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279342898,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-t9J1QD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279343592,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279343592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279343701,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl b/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl index ebb703ee55..fa7f23f3bc 100644 --- a/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279332863,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279332864,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo SNAPSHOT_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279332865,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279332868,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-lH9qMe.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279332868,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-lH9qMe.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279333505,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279333505,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279333653,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl index e9b19b4fda..fd20cb4c10 100644 --- a/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl +++ b/examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl @@ -2,7 +2,7 @@ {"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":"A file named greeting.txt in the current directory contains one word. Use the bash tool to append a second line containing the word WORLD to it (so it has two lines), then read the file back with `cat greeting.txt` to confirm, and reply with the single word DONE. Use a single bash call per action."}],"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":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Use options when possible; mark the recommended option when one is safest.","parameters":{"type":"object","properties":{"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"question":{"type":"string","description":"The specific question to ask the user."},"options":{"type":"array","description":"Optional mutually exclusive choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"value":{"type":"string","description":"Answer text returned to you if this option is selected. Defaults to label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."},"recommended":{"type":"boolean","description":"True for the recommended/default option."}},"required":["label"]}},"allow_custom":{"type":"boolean","description":"Whether the user may type a free-form answer instead of selecting an option. Defaults to true."}},"required":["question"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} diff --git a/packages/core/user-interaction/README.md b/packages/core/user-interaction/README.md index 66f812997f..6377c2b7ef 100644 --- a/packages/core/user-interaction/README.md +++ b/packages/core/user-interaction/README.md @@ -11,11 +11,13 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod ### Key Types -- `AskUserQuestionRequest` — `{ question, header?, options?, allowCustom?, agent?, signal? }`. -- `AskUserQuestionOption` — `{ label, value?, description?, recommended? }`. -- `AskUserQuestionAnswer` — `{ answer, option? }`. +- `AskUserQuestionRequest` — `{ questions: [{ id, question, header?, options?, multiSelect? }], agent?, signal? }`. +- `AskUserQuestionOption` — `{ label, description? }`. +- `AskUserQuestionAnswer` — `{ answers: [{ id, selected, custom? }] }`. - `UserInteractionProvider` — UI implementation with `ask(request)`. -- `UserInteractionError` — `HarnessError` subclass with codes such as `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`. +- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`. + +When an answer includes `custom`, `selected` is empty; custom text is an override rather than a supplement to selected choices. ## Role diff --git a/packages/core/user-interaction/src/index.ts b/packages/core/user-interaction/src/index.ts index 2e560d9574..f9c1616ade 100644 --- a/packages/core/user-interaction/src/index.ts +++ b/packages/core/user-interaction/src/index.ts @@ -21,36 +21,48 @@ declare module 'cordis' { export interface AskUserQuestionOption { /** User-facing label. */ label: string - /** Value returned to the model when selected. Defaults to `label`. */ - value?: string /** Optional extra context rendered by capable UIs. */ description?: string - /** Marks the recommended/default option. */ - recommended?: boolean } -/** Request for a human answer. */ -export interface AskUserQuestionRequest { +/** One question in an ask_user_question request. */ +export interface AskUserQuestionItem { + /** Stable model-provided question id, echoed in the answer. */ + id: string /** The question to display. */ question: string /** Optional short heading/group label. */ header?: string /** Optional choices the UI can render as a menu. */ options?: AskUserQuestionOption[] - /** Whether free-form answers are accepted. Defaults to `true`. */ - allowCustom?: boolean + /** Whether more than one option may be selected. Defaults to single-select. */ + multiSelect?: boolean +} + +/** Request for a human answer. */ +export interface AskUserQuestionRequest { + /** Questions to display. */ + questions: AskUserQuestionItem[] /** Calling agent, when the request came from an agent tool call. */ agent?: Agent /** Abort signal for the owning tool/step. */ signal?: AbortSignal } +/** Answer to one question. */ +export interface AskUserQuestionAnswerItem { + /** The answered question id. */ + id: string + /** Selected option labels. Empty when the answer is purely custom text. */ + selected: string[] + /** Optional free-text "Other" answer. */ + custom?: string +} + /** The human's answer. */ export interface AskUserQuestionAnswer { - /** Model-facing answer text. */ - answer: string - /** The selected option, when the answer came from `options`. */ - option?: AskUserQuestionOption + /** Structured answers keyed by question id. */ + answers: AskUserQuestionAnswerItem[] } /** UI-side provider for user questions. */ @@ -96,13 +108,16 @@ export class UserInteractionService extends Service { /** * Ask the active UI provider and wait for the user's answer. * - * @param request Question, options, owner agent, and abort signal. + * @param request Questions, owner agent, and abort signal. * @returns The answer chosen or typed by the human. */ async ask(request: AskUserQuestionRequest): Promise { if (request.signal?.aborted) { throw new UserInteractionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED') } + if (request.questions.length === 0) { + throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS') + } if (this.provider === undefined) { throw new UserInteractionError('no user-interaction provider is registered', 'NO_PROVIDER') } diff --git a/packages/core/user-interaction/tests/user-interaction.spec.ts b/packages/core/user-interaction/tests/user-interaction.spec.ts index 8b7eefc48c..adfbc9d4bb 100644 --- a/packages/core/user-interaction/tests/user-interaction.spec.ts +++ b/packages/core/user-interaction/tests/user-interaction.spec.ts @@ -12,7 +12,7 @@ function provider(answer = 'approved'): UserInteractionProvider & { seen: AskUse seen, async ask(request) { seen.push(request) - return { answer } + return { answers: [{ id: request.questions[0]?.id ?? 'missing', selected: [answer] }] } }, } } @@ -24,17 +24,17 @@ describe('UserInteractionService', () => { const p = provider('yes') ctx.userInteraction.registerProvider(p) - const result = await ctx.userInteraction.ask({ question: 'Proceed?' }) + const result = await ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }] }) - expect(result).toEqual({ answer: 'yes' }) - expect(p.seen).toEqual([{ question: 'Proceed?' }]) + expect(result).toEqual({ answers: [{ id: 'confirm', selected: ['yes'] }] }) + expect(p.seen).toEqual([{ questions: [{ id: 'confirm', question: 'Proceed?' }] }]) }) it('rejects ask requests when no provider is registered', async () => { const ctx = new Context() await ctx.plugin(UserInteractionService) - await expect(ctx.userInteraction.ask({ question: 'Proceed?' })) + await expect(ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }] })) .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_PROVIDER' }) }) @@ -47,7 +47,7 @@ describe('UserInteractionService', () => { dispose() dispose() - await expect(ctx.userInteraction.ask({ question: 'Proceed?' })) + await expect(ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }] })) .rejects.toMatchObject({ code: 'NO_PROVIDER' }) }) @@ -63,13 +63,24 @@ describe('UserInteractionService', () => { it('fails before reaching the provider when the signal is already aborted', async () => { const ctx = new Context() await ctx.plugin(UserInteractionService) - const p = { ask: vi.fn(async () => ({ answer: 'too late' })) } + const p = { ask: vi.fn(async () => ({ answers: [{ id: 'confirm', selected: ['too late'] }] })) } ctx.userInteraction.registerProvider(p) const controller = new AbortController() controller.abort() - await expect(ctx.userInteraction.ask({ question: 'Proceed?', signal: controller.signal })) + await expect(ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }], signal: controller.signal })) .rejects.toMatchObject({ code: 'ASK_ABORTED' }) expect(p.ask).not.toHaveBeenCalled() }) + + it('rejects empty question batches before reaching the provider', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = { ask: vi.fn(async () => ({ answers: [] })) } + ctx.userInteraction.registerProvider(p) + + await expect(ctx.userInteraction.ask({ questions: [] })) + .rejects.toMatchObject({ name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' }) + expect(p.ask).not.toHaveBeenCalled() + }) }) diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md index 85a4cd8616..49abfbff6a 100644 --- a/packages/ui/acp/README.md +++ b/packages/ui/acp/README.md @@ -30,7 +30,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name: | `session/prompt` | `agent.send()` | supports ACP `text` and `resource_link` blocks; rejects image/audio/embedded resource and empty prompts; one in-flight prompt PER session (independent); settles on the OWNING turn's end (a turn that ends in `error` rejects the RPC) | | `session/cancel` | `agent.cancel()` | the queue-aware cancel: aborts a running step, clears queued + steering work, and drops a turn about to start, then settles the prompt `cancelled` — for ONLY that session (a cancel never touches another session's stream or prompt) | | `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (the render intent — a `card`-tagged `ToolCallView`/`ToolResultView` — owned by the TOOL via `presentCall`/`presentResult`, which the bridge switches on to build the wire shape — see Tool-call presentation) | -| `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` requests to ACP form elicitations; recommended options become defaults, option descriptions are shown in enum titles, optionless requests remain free-form even when `allowCustom` is false | +| `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` questions to ACP form elicitations; option descriptions are shown in enum titles, `multi_select` uses ACP array enums, optionless requests use a required `custom` field, and a non-empty custom answer overrides any selected choice | ## Multi-session diff --git a/packages/ui/acp/src/index.ts b/packages/ui/acp/src/index.ts index 0cd25d4614..2530cca446 100644 --- a/packages/ui/acp/src/index.ts +++ b/packages/ui/acp/src/index.ts @@ -77,6 +77,8 @@ import type {} from '@deepseek-ai/dsh-session-persistence' import { UserInteractionError, type AskUserQuestionAnswer, + type AskUserQuestionAnswerItem, + type AskUserQuestionItem, type AskUserQuestionOption, type AskUserQuestionRequest, } from '@deepseek-ai/dsh-user-interaction' @@ -120,27 +122,12 @@ function sameWorkspaceCwd(left: string, right: string): boolean { return resolvePath(left) === resolvePath(right) } -function optionAnswer(option: AskUserQuestionOption): string { - return option.value ?? option.label -} - -function orderedOptions(options: readonly AskUserQuestionOption[] | undefined): AskUserQuestionOption[] { - return [...(options ?? [])].sort((a, b) => Number(Boolean(b.recommended)) - Number(Boolean(a.recommended))) -} - function optionDescription(option: AskUserQuestionOption): string { return option.description === undefined ? option.label : `${option.label}: ${option.description}` } -function selectedOption( - options: readonly AskUserQuestionOption[], - answer: string, -): AskUserQuestionOption | undefined { - return options.find(option => optionAnswer(option) === answer) -} - function requireStringContent( content: Record | null | undefined, key: string, @@ -177,62 +164,74 @@ function withAbort(promise: Promise, signal: AbortSignal | undefined): Pro function elicitationForQuestion( sessionId: SessionId, - request: AskUserQuestionRequest, + question: AskUserQuestionItem, options: AskUserQuestionOption[], ): CreateElicitationRequest { - const allowCustom = options.length === 0 || (request.allowCustom ?? true) - const title = request.header ?? 'Question' + const title = question.header ?? 'Question' if (options.length === 0) { return { sessionId, mode: 'form', - message: request.question, + message: question.question, requestedSchema: { type: 'object', title, properties: { - answer: { type: 'string', title: request.question }, + custom: { type: 'string', title: question.question }, }, - required: ['answer'], + required: ['custom'], }, } } const choiceOptions: EnumOption[] = options.map(option => ({ - const: optionAnswer(option), + const: option.label, title: optionDescription(option), })) - const recommended = options.find(option => option.recommended) + const choice = question.multiSelect === true + ? { + type: 'array' as const, + title: question.question, + description: 'Choose one or more options, or fill a custom answer below.', + items: { + anyOf: choiceOptions, + }, + } + : { + type: 'string' as const, + title: question.question, + description: 'Choose one option, or fill a custom answer below.', + oneOf: choiceOptions, + } return { sessionId, mode: 'form', - message: request.question, + message: question.question, requestedSchema: { type: 'object', title, properties: { - choice: { + choice, + custom: { type: 'string', - title: request.question, - description: allowCustom ? 'Choose one option, or fill a custom answer below.' : 'Choose one option.', - oneOf: choiceOptions, - ...recommended !== undefined ? { default: optionAnswer(recommended) } : {}, + title: 'Custom answer', + description: 'Optional free-form answer. Leave empty to use the selected option.', }, - ...allowCustom - ? { - custom_answer: { - type: 'string' as const, - title: 'Custom answer', - description: 'Optional free-form answer. Leave empty to use the selected option.', - }, - } - : {}, }, - required: allowCustom ? [] : ['choice'], + required: [], }, } } +function stringArrayContent( + content: Record | null | undefined, + key: string, +): string[] { + const value = content?.[key] + if (Array.isArray(value)) return value.filter((item): item is string => typeof item === 'string' && item.length > 0) + return typeof value === 'string' && value.length > 0 ? [value] : [] +} + /** Plugin config: the agent template ACP sessions are created from. */ export interface AcpConfig { /** Model name for created agents (must have a registered adapter). */ @@ -373,25 +372,30 @@ export function apply(ctx: Context, config: AcpConfig): void { if (sessionId === undefined) { throw new UserInteractionError('ACP user question has no matching session', 'NO_SESSION') } - const options = orderedOptions(request.options) - const response = await withAbort(conn.unstable_createElicitation( - elicitationForQuestion(sessionId, request, options), - ), request.signal).catch((error: unknown) => { - if (error instanceof UserInteractionError) throw error - throw new UserInteractionError('ACP elicitation request failed', 'ASK_FAILED', { cause: error }) - }) - if (response.action !== 'accept') { - throw new UserInteractionError('ask_user_question was cancelled by the user', 'ASK_CANCELLED') + const answers: AskUserQuestionAnswerItem[] = [] + for (const question of request.questions) { + const options = question.options ?? [] + const response = await withAbort(conn.unstable_createElicitation( + elicitationForQuestion(sessionId, question, options), + ), request.signal).catch((error: unknown) => { + if (error instanceof UserInteractionError) throw error + throw new UserInteractionError('ACP elicitation request failed', 'ASK_FAILED', { cause: error }) + }) + if (response.action !== 'accept') { + throw new UserInteractionError('ask_user_question was cancelled by the user', 'ASK_CANCELLED') + } + const custom = requireStringContent(response.content, 'custom') + const selected = stringArrayContent(response.content, 'choice') + if (custom === undefined && selected.length === 0) { + throw new UserInteractionError('ask_user_question returned no answer', 'NO_ANSWER') + } + answers.push({ + id: question.id, + selected: custom === undefined ? selected : [], + ...custom !== undefined ? { custom } : {}, + }) } - const customAnswer = requireStringContent(response.content, 'custom_answer') - if (customAnswer !== undefined) return { answer: customAnswer } - - const answer = requireStringContent(response.content, options.length === 0 ? 'answer' : 'choice') - if (answer === undefined) { - throw new UserInteractionError('ask_user_question returned no answer', 'NO_ANSWER') - } - const option = selectedOption(options, answer) - return option === undefined ? { answer } : { answer, option } + return { answers } }, }) diff --git a/packages/ui/acp/tests/bridge.spec.ts b/packages/ui/acp/tests/bridge.spec.ts index 969c10a2da..be05a09644 100644 --- a/packages/ui/acp/tests/bridge.spec.ts +++ b/packages/ui/acp/tests/bridge.spec.ts @@ -59,18 +59,20 @@ describe('acp bridge', () => { withAskUser: true, script: [ toolCallResponse('ask-1', 'ask_user_question', { - header: 'Project config', - question: 'Which language should I use?', - options: [ - { label: 'TypeScript', value: 'ts', description: 'Good for UI apps' }, - { label: 'Python', value: 'py', description: 'Good for scripts', recommended: true }, - ], - allow_custom: false, + questions: [{ + id: 'language', + header: 'Project config', + question: 'Which language should I use?', + options: [ + { label: 'TypeScript', description: 'Good for UI apps' }, + { label: 'Python', description: 'Good for scripts' }, + ], + }], }), textResponse('Python it is.'), ], }) - harness.onElicitation = () => ({ action: 'accept', content: { choice: 'py' } }) + harness.onElicitation = () => ({ action: 'accept', content: { choice: 'Python' } }) await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) @@ -86,18 +88,20 @@ describe('acp bridge', () => { title: 'Project config', properties: { choice: { - default: 'py', oneOf: [ - { const: 'py', title: 'Python: Good for scripts' }, - { const: 'ts', title: 'TypeScript: Good for UI apps' }, + { const: 'TypeScript', title: 'TypeScript: Good for UI apps' }, + { const: 'Python', title: 'Python: Good for scripts' }, ], }, + custom: { type: 'string' }, }, - required: ['choice'], + required: [], }, }) const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result') - expect(JSON.stringify(toolResult)).toContain('py') + const toolResultBlock = toolResult?.type === 'tool/result' ? toolResult.data.content[0] : undefined + const toolResultText = toolResultBlock?.type === 'text' ? toolResultBlock.text : undefined + expect(toolResultText).toBe('{"answers":[{"id":"language","selected":["Python"]}]}') }) it('routes optionless ask_user_question through an ACP free-form answer field', async () => { @@ -106,13 +110,12 @@ describe('acp bridge', () => { withAskUser: true, script: [ toolCallResponse('ask-1', 'ask_user_question', { - question: 'What should I name it?', - allow_custom: false, + questions: [{ id: 'name', question: 'What should I name it?' }], }), textResponse('Name recorded.'), ], }) - harness.onElicitation = () => ({ action: 'accept', content: { answer: 'apollo' } }) + harness.onElicitation = () => ({ action: 'accept', content: { custom: 'apollo' } }) await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) @@ -120,8 +123,8 @@ describe('acp bridge', () => { expect(harness.elicitationRequests[0]).toMatchObject({ requestedSchema: { - properties: { answer: { type: 'string', title: 'What should I name it?' } }, - required: ['answer'], + properties: { custom: { type: 'string', title: 'What should I name it?' } }, + required: ['custom'], }, }) const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result') @@ -130,18 +133,21 @@ describe('acp bridge', () => { it('supports ACP custom answers alongside choices', async () => { harness = await makeBridgeHarness({ storageDir, withAskUser: true }) - harness.onElicitation = () => ({ action: 'accept', content: { custom_answer: 'Use Zig' } }) + harness.onElicitation = () => ({ action: 'accept', content: { custom: 'Use Zig' } }) await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) const agent = harness.ctx.agents.get(AgentId(sessionId))! const result = await harness.ctx.userInteraction.ask({ agent, - question: 'Which language?', - options: [{ label: 'TypeScript' }], + questions: [{ + id: 'language', + question: 'Which language?', + options: [{ label: 'TypeScript' }], + }], }) - expect(result).toEqual({ answer: 'Use Zig' }) + expect(result).toEqual({ answers: [{ id: 'language', selected: [], custom: 'Use Zig' }] }) expect(harness.elicitationRequests[0]).toMatchObject({ requestedSchema: { properties: { @@ -149,26 +155,46 @@ describe('acp bridge', () => { description: 'Choose one option, or fill a custom answer below.', oneOf: [{ const: 'TypeScript', title: 'TypeScript' }], }, - custom_answer: { type: 'string' }, + custom: { type: 'string' }, }, required: [], }, }) }) - it('returns raw ACP answers when they do not match a provided option', async () => { + it('treats ACP custom answers as overriding selected choices', async () => { harness = await makeBridgeHarness({ storageDir, withAskUser: true }) - harness.onElicitation = () => ({ action: 'accept', content: { choice: 'something else' } }) + harness.onElicitation = () => ({ action: 'accept', content: { choice: 'TypeScript', custom: 'Use Zig' } }) await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) const agent = harness.ctx.agents.get(AgentId(sessionId))! await expect(harness.ctx.userInteraction.ask({ agent, - question: 'Pick', - options: [{ label: 'A', value: 'a' }], - allowCustom: false, - })).resolves.toEqual({ answer: 'something else' }) + questions: [{ + id: 'language', + question: 'Which language?', + options: [{ label: 'TypeScript' }], + }], + })).resolves.toEqual({ answers: [{ id: 'language', selected: [], custom: 'Use Zig' }] }) + }) + + it('supports ACP multi-select answers', async () => { + harness = await makeBridgeHarness({ storageDir, withAskUser: true }) + harness.onElicitation = () => ({ action: 'accept', content: { choice: ['Tests', 'Docs'] } }) + await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} }) + const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) + const agent = harness.ctx.agents.get(AgentId(sessionId))! + + await expect(harness.ctx.userInteraction.ask({ + agent, + questions: [{ + id: 'targets', + question: 'Pick', + options: [{ label: 'Tests' }, { label: 'Docs' }], + multiSelect: true, + }], + })).resolves.toEqual({ answers: [{ id: 'targets', selected: ['Tests', 'Docs'] }] }) }) it('reports ACP ask-user routing and answer failures as structured errors', async () => { @@ -177,21 +203,21 @@ describe('acp bridge', () => { const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] }) const agent = harness.ctx.agents.get(AgentId(sessionId))! - await expect(harness.ctx.userInteraction.ask({ question: 'No agent?' })) + await expect(harness.ctx.userInteraction.ask({ questions: [{ id: 'x', question: 'No agent?' }] })) .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_AGENT' }) - await expect(harness.ctx.userInteraction.ask({ agent: { id: 'other' } as typeof agent, question: 'No session?' })) + await expect(harness.ctx.userInteraction.ask({ agent: { id: 'other' } as typeof agent, questions: [{ id: 'x', question: 'No session?' }] })) .rejects.toMatchObject({ code: 'NO_SESSION' }) harness.onElicitation = () => ({ action: 'cancel' }) - await expect(harness.ctx.userInteraction.ask({ agent, question: 'Cancel?' })) + await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Cancel?' }] })) .rejects.toMatchObject({ code: 'ASK_CANCELLED' }) harness.onElicitation = () => ({ action: 'accept', content: {} }) - await expect(harness.ctx.userInteraction.ask({ agent, question: 'Empty?' })) + await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Empty?' }] })) .rejects.toMatchObject({ code: 'NO_ANSWER' }) harness.onElicitation = () => { throw new Error('client boom') } - await expect(harness.ctx.userInteraction.ask({ agent, question: 'Client fails?', signal: new AbortController().signal })) + await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Client fails?' }], signal: new AbortController().signal })) .rejects.toMatchObject({ code: 'ASK_FAILED' }) }) @@ -203,7 +229,7 @@ describe('acp bridge', () => { const alreadyAborted = new AbortController() alreadyAborted.abort() - await expect(harness.ctx.userInteraction.ask({ agent, question: 'Already?', signal: alreadyAborted.signal })) + await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Already?' }], signal: alreadyAborted.signal })) .rejects.toMatchObject({ code: 'ASK_ABORTED' }) let abortedReads = 0 @@ -216,18 +242,18 @@ describe('acp bridge', () => { reason: undefined, throwIfAborted() {}, } as AbortSignal - await expect(harness.ctx.userInteraction.ask({ agent, question: 'Raced?', signal: racingAbort })) + await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Raced?' }], signal: racingAbort })) .rejects.toMatchObject({ code: 'ASK_ABORTED' }) - let release: ((value: { action: 'accept'; content: { answer: string } }) => void) | undefined + let release: ((value: { action: 'accept'; content: { custom: string } }) => void) | undefined harness.onElicitation = () => new Promise((resolve) => { release = resolve }) const pendingAbort = new AbortController() - const ask = harness.ctx.userInteraction.ask({ agent, question: 'Pending?', signal: pendingAbort.signal }) + const ask = harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Pending?' }], signal: pendingAbort.signal }) await new Promise(resolve => setImmediate(resolve)) pendingAbort.abort() await expect(ask).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - release?.({ action: 'accept', content: { answer: 'too late' } }) + release?.({ action: 'accept', content: { custom: 'too late' } }) }) it('allows multiple concurrent sessions, each with a distinct id', async () => { diff --git a/packages/ui/stdio-agent/src/stdio-chat.ts b/packages/ui/stdio-agent/src/stdio-chat.ts index 715ff541b5..4745aefb47 100644 --- a/packages/ui/stdio-agent/src/stdio-chat.ts +++ b/packages/ui/stdio-agent/src/stdio-chat.ts @@ -23,6 +23,8 @@ import { AgentId } from '@deepseek-ai/dsh-agent' import { UserInteractionError, type AskUserQuestionAnswer, + type AskUserQuestionAnswerItem, + type AskUserQuestionItem, type AskUserQuestionOption, type AskUserQuestionRequest, } from '@deepseek-ai/dsh-user-interaction' @@ -63,27 +65,20 @@ function isTTYPair(input: Readable, output: Writable): boolean { return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY) } -function optionAnswer(option: AskUserQuestionOption): string { - return option.value ?? option.label -} - -function displayOptions(options: AskUserQuestionOption[] = []): AskUserQuestionOption[] { - return options - .map((option, index) => ({ option, index })) - .sort((left, right) => { - if (left.option.recommended === right.option.recommended) return left.index - right.index - return left.option.recommended ? -1 : 1 - }) - .map(({ option }) => option) -} - interface PendingQuestion { request: AskUserQuestionRequest + questionIndex: number + answers: AskUserQuestionAnswerItem[] resolve(answer: AskUserQuestionAnswer): void reject(error: unknown): void onAbort: () => void } +type OptionSelection = + | { kind: 'selected'; options: AskUserQuestionOption[] } + | { kind: 'custom' } + | { kind: 'invalid' } + /** * The plugin body, parameterized over its I/O runtime. `apply` is the thin * production wrapper that binds the real `process` streams; tests call this @@ -205,12 +200,16 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt if (status === 'idle') maybeExit() }) + const activeQuestionItem = (pending: PendingQuestion): AskUserQuestionItem => + pending.request.questions[pending.questionIndex] as AskUserQuestionItem + const renderQuestion = (pending: PendingQuestion): void => { - const { request } = pending + const question = activeQuestionItem(pending) + const options = question.options ?? [] output.write('\n') - output.write(request.header ? `[${request.header}] ${request.question}\n` : `[question] ${request.question}\n`) - displayOptions(request.options).forEach((option, index) => { - output.write(` ${index + 1}. ${option.label}${option.recommended ? ' (recommended)' : ''}\n`) + output.write(question.header ? `[${question.header}] ${question.question}\n` : `${question.question}\n`) + options.forEach((option, index) => { + output.write(` ${index + 1}. ${option.label}\n`) if (option.description) output.write(` ${option.description}\n`) }) output.write('> ') @@ -249,41 +248,64 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt } } - const finishQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswer): void => { - removeAbortListener(pending) + const finishQuestion = (pending: PendingQuestion): void => { activeQuestion = undefined - pending.resolve(answer) + removeAbortListener(pending) + pending.resolve({ answers: pending.answers }) output.write('\n') startNextQuestion() } + const answerCurrentQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswerItem): void => { + pending.answers.push(answer) + pending.questionIndex += 1 + if (pending.questionIndex >= pending.request.questions.length) { + finishQuestion(pending) + return + } + renderQuestion(pending) + } + + const selectedOptions = (text: string, options: AskUserQuestionOption[], multiSelect: boolean): OptionSelection => { + if (text === '') return { kind: 'invalid' } + if (!multiSelect) { + if (!/^\d+$/.test(text)) return { kind: 'custom' } + const selected = options[Number(text) - 1] + return selected === undefined ? { kind: 'invalid' } : { kind: 'selected', options: [selected] } + } + const indices = text.split(/[,\s]+/).filter(Boolean) + if (indices.length === 0) return { kind: 'invalid' } + if (indices.some(part => !/^\d+$/.test(part))) return { kind: 'custom' } + const uniqueIndices = [...new Set(indices)] + const selected = uniqueIndices.map(part => options[Number(part) - 1]) + return selected.some(option => option === undefined) + ? { kind: 'invalid' } + : { kind: 'selected', options: selected as AskUserQuestionOption[] } + } + const answerQuestion = (line: string): void => { const pending = activeQuestion as PendingQuestion + const question = activeQuestionItem(pending) const text = line.trim() - const options = displayOptions(pending.request.options) - const selectedIndex = /^\d+$/.test(text) ? Number(text) - 1 : -1 - const selected = selectedIndex >= 0 ? options[selectedIndex] : undefined - if (selected !== undefined) { - finishQuestion(pending, { answer: optionAnswer(selected), option: selected }) + const options = question.options ?? [] + const selection = options.length > 0 + ? selectedOptions(text, options, question.multiSelect ?? false) + : { kind: text === '' ? 'invalid' : 'custom' } as OptionSelection + if (selection.kind === 'selected') { + answerCurrentQuestion(pending, { id: question.id, selected: selection.options.map(option => option.label) }) return } - const recommended = options.find(option => option.recommended) - if (text === '' && recommended !== undefined) { - finishQuestion(pending, { answer: optionAnswer(recommended), option: recommended }) - return - } - - const allowCustom = options.length === 0 || (pending.request.allowCustom ?? true) - if (allowCustom && text !== '') { - finishQuestion(pending, { answer: text }) + if (selection.kind === 'custom' && text !== '') { + answerCurrentQuestion(pending, { id: question.id, selected: [], custom: text }) return } output.write(options.length > 0 ? 'Please enter one of the option numbers' - + (allowCustom ? ' or a custom answer' : '') + + (question.multiSelect ? ' (comma or space separated)' : '') + + ' or a custom answer' + '.\n> ' : 'Please enter an answer.\n> ') } @@ -298,6 +320,8 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt return new Promise((resolve, reject) => { const pending: PendingQuestion = { request, + questionIndex: 0, + answers: [], resolve, reject, onAbort: () => { diff --git a/packages/ui/stdio-agent/tests/stdio-chat.spec.ts b/packages/ui/stdio-agent/tests/stdio-chat.spec.ts index 66d94bc1eb..1f4b44e1cf 100644 --- a/packages/ui/stdio-agent/tests/stdio-chat.spec.ts +++ b/packages/ui/stdio-agent/tests/stdio-chat.spec.ts @@ -1,4 +1,4 @@ -import { Readable } from 'node:stream' +import { Readable, Writable } from 'node:stream' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' @@ -107,6 +107,30 @@ describe('createStdioChat rendering', () => { // And it drives the default agent id 'main'. }) + it('detects readline terminal mode from both stream TTY flags', async () => { + for (const [inputTTY, outputTTY] of [[true, false], [true, true]] as const) { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(UserInteractionService) + let text = '' + const output = new Writable({ + write(chunk, _encoding, callback) { + text += String(chunk) + callback() + }, + }) as Writable & { isTTY?: boolean } + const { runtime } = makeRuntime({ output }) + ;(runtime.input as Readable & { isTTY?: boolean }).isTTY = inputTTY + output.isTTY = outputTTY + const fiber = await ctx.plugin(Object.assign((inner: Context) => { + createStdioChat(inner, CONFIG, runtime) + }, { inject: ['agents', 'userInteraction'] })) + + expect(text).toContain('hi there') + await fiber.dispose() + } + }) + it('renders text-delta chunks verbatim', async () => { const { ctx, out } = await setup() ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' })) @@ -273,150 +297,229 @@ describe('createStdioChat input', () => { ctx.agents.register(agent) const answer = ctx.userInteraction.ask({ - header: 'Confirm', - question: 'Proceed with the edit?', - options: [{ label: 'Yes', value: 'Proceed', description: 'Apply the edit now.', recommended: true }], + questions: [{ + id: 'confirm', + header: 'Confirm', + question: 'Proceed with the edit?', + options: [{ label: 'Yes', description: 'Apply the edit now.' }], + }], }) await new Promise(r => setImmediate(r)) input.feed('Use a smaller change') - await expect(answer).resolves.toEqual({ answer: 'Use a smaller change' }) + await expect(answer).resolves.toEqual({ answers: [{ id: 'confirm', selected: [], custom: 'Use a smaller change' }] }) expect(agent.sent).toEqual([]) expect(out.text()).toContain('[Confirm] Proceed with the edit?') - expect(out.text()).toContain('1. Yes (recommended)') + expect(out.text()).toContain('1. Yes') expect(out.text()).toContain('Apply the edit now.') }) it('answers a pending user question by numeric option selection', async () => { const { ctx, input } = await setup() const answer = ctx.userInteraction.ask({ - question: 'Which mode?', - options: [ - { label: 'Safe', value: 'Use safe mode', recommended: true }, - { label: 'Fast', value: 'Use fast mode' }, - ], - allowCustom: false, + questions: [{ + id: 'mode', + question: 'Which mode?', + options: [ + { label: 'Safe' }, + { label: 'Fast' }, + ], + }], }) await new Promise(r => setImmediate(r)) input.feed('2') await expect(answer).resolves.toEqual({ - answer: 'Use fast mode', - option: { label: 'Fast', value: 'Use fast mode' }, + answers: [{ id: 'mode', selected: ['Fast'] }], }) }) - it('renders recommended options first and selects by displayed number', async () => { + it('renders options in input order and selects by displayed number', async () => { const { ctx, input, out } = await setup() const answer = ctx.userInteraction.ask({ - question: 'Which topic?', - options: [ - { label: 'Hobbies', value: 'hobbies' }, - { label: 'Work', value: 'work', description: 'Questions about current projects.' }, - { label: 'Casual', value: 'casual', recommended: true, description: 'Easy conversation.' }, - ], - allowCustom: false, + questions: [{ + id: 'topic', + question: 'Which topic?', + options: [ + { label: 'Hobbies' }, + { label: 'Work', description: 'Questions about current projects.' }, + { label: 'Casual', description: 'Easy conversation.' }, + ], + }], }) await new Promise(r => setImmediate(r)) expect(out.text()).toContain([ - '[question] Which topic?', - ' 1. Casual (recommended)', - ' Easy conversation.', - ' 2. Hobbies', - ' 3. Work', + 'Which topic?', + ' 1. Hobbies', + ' 2. Work', ' Questions about current projects.', + ' 3. Casual', + ' Easy conversation.', ].join('\n')) - input.feed('1') + input.feed('3') await expect(answer).resolves.toEqual({ - answer: 'casual', - option: { label: 'Casual', value: 'casual', recommended: true, description: 'Easy conversation.' }, + answers: [{ id: 'topic', selected: ['Casual'] }], }) }) - it('uses the recommended option when the user submits an empty answer', async () => { + it('answers a multi-select question with multiple numeric selections', async () => { const { ctx, input } = await setup() const answer = ctx.userInteraction.ask({ - question: 'Continue?', - options: [ - { label: 'No' }, - { label: 'Yes', value: 'Continue', recommended: true }, - ], - allowCustom: false, + questions: [{ + id: 'targets', + question: 'What should I update?', + options: [{ label: 'Tests' }, { label: 'Docs' }, { label: 'Code' }], + multiSelect: true, + }], }) await new Promise(r => setImmediate(r)) - input.feed('') + input.feed('1 1, 3') await expect(answer).resolves.toEqual({ - answer: 'Continue', - option: { label: 'Yes', value: 'Continue', recommended: true }, + answers: [{ id: 'targets', selected: ['Tests', 'Code'] }], }) }) - it('re-prompts when options are required and the input is invalid', async () => { - const { ctx, input, out } = await setup() + it('accepts non-numeric multi-select input as a custom answer', async () => { + const { ctx, input } = await setup() const answer = ctx.userInteraction.ask({ - question: 'Which mode?', - options: [{ label: 'Safe' }], - allowCustom: false, + questions: [{ + id: 'targets', + question: 'What should I update?', + options: [{ label: 'Tests' }, { label: 'Docs' }], + multiSelect: true, + }], }) await new Promise(r => setImmediate(r)) - input.feed('custom') + input.feed('the release notes') + + await expect(answer).resolves.toEqual({ + answers: [{ id: 'targets', selected: [], custom: 'the release notes' }], + }) + }) + + it('asks every question in a batch and returns answers by id', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + questions: [ + { id: 'language', question: 'Which language?', options: [{ label: 'Python' }, { label: 'TypeScript' }] }, + { id: 'note', question: 'Any note?' }, + ], + }) await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('Please enter one of the option numbers.') + input.feed('2') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('\nAny note?\n') + input.feed('ship today') + + await expect(answer).resolves.toEqual({ + answers: [ + { id: 'language', selected: ['TypeScript'] }, + { id: 'note', selected: [], custom: 'ship today' }, + ], + }) + }) + + it('re-prompts when option input is invalid', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + questions: [{ + id: 'mode', + question: 'Which mode?', + options: [{ label: 'Safe' }], + multiSelect: true, + }], + }) + await new Promise(r => setImmediate(r)) + input.feed('2') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.') input.feed('1') await expect(answer).resolves.toEqual({ - answer: 'Safe', - option: { label: 'Safe' }, + answers: [{ id: 'mode', selected: ['Safe'] }], }) }) - it('re-prompts with custom-answer guidance when options also allow free-form input', async () => { + it('re-prompts when single-select option input is out of range', async () => { const { ctx, input, out } = await setup() const answer = ctx.userInteraction.ask({ - question: 'Which mode?', - options: [{ label: 'Safe' }], + questions: [{ + id: 'mode', + question: 'Which mode?', + options: [{ label: 'Safe' }], + }], + }) + await new Promise(r => setImmediate(r)) + input.feed('2') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.') + input.feed('1') + + await expect(answer).resolves.toEqual({ + answers: [{ id: 'mode', selected: ['Safe'] }], + }) + }) + + it('re-prompts when multi-select input contains no option numbers', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + questions: [{ + id: 'mode', + question: 'Which mode?', + options: [{ label: 'Safe' }], + multiSelect: true, + }], + }) + await new Promise(r => setImmediate(r)) + input.feed(',') + await new Promise(r => setImmediate(r)) + expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.') + input.feed('1') + + await expect(answer).resolves.toEqual({ + answers: [{ id: 'mode', selected: ['Safe'] }], + }) + }) + + it('re-prompts when an option question receives an empty answer', async () => { + const { ctx, input, out } = await setup() + const answer = ctx.userInteraction.ask({ + questions: [{ + id: 'mode', + question: 'Which mode?', + options: [{ label: 'Safe' }], + }], }) await new Promise(r => setImmediate(r)) input.feed('') await new Promise(r => setImmediate(r)) expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.') - input.feed('Use custom mode') + input.feed('1') - await expect(answer).resolves.toEqual({ answer: 'Use custom mode' }) + await expect(answer).resolves.toEqual({ + answers: [{ id: 'mode', selected: ['Safe'] }], + }) }) - it('re-prompts when a free-form question receives an empty answer', async () => { + it('re-prompts when a question receives an empty answer', async () => { const { ctx, input, out } = await setup() - const answer = ctx.userInteraction.ask({ question: 'What should I use?' }) + const answer = ctx.userInteraction.ask({ questions: [{ id: 'path', question: 'What should I use?' }] }) await new Promise(r => setImmediate(r)) input.feed('') await new Promise(r => setImmediate(r)) expect(out.text()).toContain('Please enter an answer.') input.feed('Use defaults') - await expect(answer).resolves.toEqual({ answer: 'Use defaults' }) - }) - - it('accepts free-form input for an optionless question even when allowCustom is false', async () => { - const { ctx, input } = await setup() - const answer = ctx.userInteraction.ask({ - question: 'Choose?', - allowCustom: false, - }) - await new Promise(r => setImmediate(r)) - - input.feed('Use the default path') - - await expect(answer).resolves.toEqual({ answer: 'Use the default path' }) + await expect(answer).resolves.toEqual({ answers: [{ id: 'path', selected: [], custom: 'Use defaults' }] }) }) it('rejects an active question when its signal aborts', async () => { const { ctx } = await setup() const controller = new AbortController() - const answer = ctx.userInteraction.ask({ question: 'Continue?', signal: controller.signal }) + const answer = ctx.userInteraction.ask({ questions: [{ id: 'continue', question: 'Continue?' }], signal: controller.signal }) const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' }) await new Promise(r => setImmediate(r)) @@ -428,40 +531,40 @@ describe('createStdioChat input', () => { it('continues to the next queued question when the active question aborts', async () => { const { ctx, input, out } = await setup() const controller = new AbortController() - const first = ctx.userInteraction.ask({ question: 'First?', signal: controller.signal }) + const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }], signal: controller.signal }) const firstRejected = expect(first).rejects.toMatchObject({ code: 'ASK_ABORTED' }) - const second = ctx.userInteraction.ask({ question: 'Second?' }) + const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }] }) await new Promise(r => setImmediate(r)) controller.abort() await firstRejected await new Promise(r => setImmediate(r)) - expect(out.text()).toContain('[question] Second?') + expect(out.text()).toContain('\nSecond?\n') input.feed('second answer') - await expect(second).resolves.toEqual({ answer: 'second answer' }) + await expect(second).resolves.toEqual({ answers: [{ id: 'second', selected: [], custom: 'second answer' }] }) }) it('skips a queued question whose signal aborted before it became active', async () => { const { ctx, input, out } = await setup() const controller = new AbortController() - const first = ctx.userInteraction.ask({ question: 'First?' }) - const second = ctx.userInteraction.ask({ question: 'Second?', signal: controller.signal }) + const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] }) + const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal }) const secondRejected = expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' }) await new Promise(r => setImmediate(r)) controller.abort() input.feed('first answer') - await expect(first).resolves.toEqual({ answer: 'first answer' }) + await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] }) await secondRejected - expect(out.text()).not.toContain('[question] Second?') + expect(out.text()).not.toContain('\nSecond?\n') }) it('rejects active and queued questions when the UI is disposed', async () => { const { ctx, fiber } = await setup() - const active = ctx.userInteraction.ask({ question: 'Active?' }) - const queued = ctx.userInteraction.ask({ question: 'Queued?' }) + const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] }) + const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] }) const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' }) const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' }) await new Promise(r => setImmediate(r)) @@ -474,8 +577,8 @@ describe('createStdioChat input', () => { it('rejects active and queued questions when stdin closes before the user answers', async () => { const { ctx, input, exit } = await setup() - const active = ctx.userInteraction.ask({ question: 'Active?' }) - const queued = ctx.userInteraction.ask({ question: 'Queued?' }) + const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] }) + const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] }) const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' }) const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' }) await new Promise(r => setImmediate(r)) @@ -494,7 +597,7 @@ describe('createStdioChat input', () => { await new Promise(r => setImmediate(r)) const before = out.text() - const answer = ctx.userInteraction.ask({ question: 'Too late?' }) + const answer = ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Too late?' }] }) await expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' }) expect(out.text()).toBe(before) diff --git a/packages/ui/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md index dc0b198d04..11f35c5129 100644 --- a/packages/ui/tool-ask-user/README.md +++ b/packages/ui/tool-ask-user/README.md @@ -6,12 +6,14 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo `ask_user_question` accepts: -- `question` — required question text. +- `questions` — required non-empty array of question objects. +- `id` — required stable id on each question, echoed in the answer. +- `question` — required question text for each question. - `header` — optional short heading. -- `options` — optional choices with `label`, `value`, `description`, and `recommended`. -- `allow_custom` — whether free-form answers are allowed; defaults to the provider's normal `true` behavior. +- `options` — optional choices with `label` and `description`. +- `multi_select` — whether that question may return more than one selected option. -The tool calls `ctx.userInteraction.ask()` and returns the selected option value or custom answer as a text tool result. +The tool calls `ctx.userInteraction.ask()` and returns JSON text shaped as `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices. ## Role diff --git a/packages/ui/tool-ask-user/src/index.ts b/packages/ui/tool-ask-user/src/index.ts index e574db91f3..6048f66808 100644 --- a/packages/ui/tool-ask-user/src/index.ts +++ b/packages/ui/tool-ask-user/src/index.ts @@ -8,56 +8,64 @@ import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' -import type {} from '@deepseek-ai/dsh-user-interaction' +import '@deepseek-ai/dsh-user-interaction' export const name = 'tool-ask-user' export const inject = ['tools', 'userInteraction'] const description = 'Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. ' - + 'Use options when possible; mark the recommended option when one is safest.' + + 'Send one or more questions, each with a stable id that will be echoed in the answer.' export function apply(ctx: Context): void { ctx.tools.register(defineTool({ name: 'ask_user_question', description, parameters: { - header: { - type: 'string', - description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".', - }, - question: { - type: 'string', - required: true, - description: 'The specific question to ask the user.', - }, - options: { + questions: { type: 'array', - description: 'Optional mutually exclusive choices to show the user.', + required: true, + description: 'Questions to ask the user before continuing.', items: { type: 'object', properties: { - label: { type: 'string', required: true, description: 'Short user-facing option label.' }, - value: { type: 'string', description: 'Answer text returned to you if this option is selected. Defaults to label.' }, - description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' }, - recommended: { type: 'boolean', description: 'True for the recommended/default option.' }, + id: { type: 'string', required: true, description: 'Stable id for this question; echoed in the answer.' }, + question: { type: 'string', required: true, description: 'The specific question to ask the user.' }, + header: { + type: 'string', + description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".', + }, + options: { + type: 'array', + description: 'Optional choices to show the user.', + items: { + type: 'object', + properties: { + label: { type: 'string', required: true, description: 'Short user-facing option label.' }, + description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' }, + }, + }, + }, + multi_select: { + type: 'boolean', + description: 'Whether the user may select more than one option. Defaults to false.', + }, }, }, }, - allow_custom: { - type: 'boolean', - description: 'Whether the user may type a free-form answer instead of selecting an option. Defaults to true.', - }, }, async execute(args, exec) { const result = await ctx.userInteraction.ask({ - question: args.question, - ...args.header !== undefined ? { header: args.header } : {}, - ...args.options !== undefined ? { options: args.options } : {}, - ...args.allow_custom !== undefined ? { allowCustom: args.allow_custom } : {}, + questions: args.questions.map(question => ({ + id: question.id, + question: question.question, + ...question.header !== undefined ? { header: question.header } : {}, + ...question.options !== undefined ? { options: question.options } : {}, + ...question.multi_select !== undefined ? { multiSelect: question.multi_select } : {}, + })), ...exec.agent !== undefined ? { agent: exec.agent } : {}, ...exec.signal !== undefined ? { signal: exec.signal } : {}, }) - return [{ type: 'text', text: result.answer }] + return [{ type: 'text', text: JSON.stringify(result) }] }, })) } diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts index b6fd9d92e4..b0fdd2cc41 100644 --- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts +++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts @@ -9,9 +9,15 @@ import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' interface OptionSchemaShape { properties: { - options: { + questions: { items: { - properties: Record + properties: { + options: { + items: { + properties: Record + } + } + } & Record } } } @@ -36,29 +42,35 @@ describe('ask_user_question tool', () => { parameters: { type: 'object', properties: { - question: { type: 'string' }, - options: { type: 'array' }, - allow_custom: { type: 'boolean' }, + questions: { type: 'array' }, }, - required: ['question'], + required: ['questions'], }, }) const parameters = schema?.parameters as unknown as OptionSchemaShape - expect(parameters.properties.options.items.properties).toMatchObject({ - description: { type: 'string' }, - recommended: { type: 'boolean' }, + expect(parameters.properties.questions.items.properties).toMatchObject({ + id: { type: 'string' }, + question: { type: 'string' }, + header: { type: 'string' }, + options: { type: 'array' }, + multi_select: { type: 'boolean' }, }) - expect(parameters.properties.options.items.properties).not.toHaveProperty('desc') + expect(parameters.properties.questions.items.properties.options.items.properties).toMatchObject({ + label: { type: 'string' }, + description: { type: 'string' }, + }) + expect(parameters.properties.questions.items.properties.options.items.properties).not.toHaveProperty('value') + expect(parameters.properties.questions.items.properties.options.items.properties).not.toHaveProperty('recommended') + expect(parameters.properties.questions.items.properties.options.items.properties).not.toHaveProperty('preview') }) - it('asks the registered user-interaction provider and returns the answer text', async () => { + it('asks the registered user-interaction provider and projects structured answers to text', async () => { const ctx = await setup() const seen: AskUserQuestionRequest[] = [] ctx.userInteraction.registerProvider({ async ask(request) { seen.push(request) - const option = request.options?.[0] - return option === undefined ? { answer: 'Use pnpm' } : { answer: 'Use pnpm', option } + return { answers: [{ id: 'pkg', selected: ['pnpm'] }] } }, }) @@ -66,20 +78,59 @@ describe('ask_user_question tool', () => { callId: CallId('ask-1'), name: 'ask_user_question', arguments: { - question: 'Which package manager should I use?', - options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }], - allow_custom: false, + questions: [{ + id: 'pkg', + question: 'Which package manager should I use?', + options: [{ label: 'pnpm', description: 'Use pnpm workspaces.' }], + }], }, }) expect(result).toMatchObject({ isError: false, - content: [{ type: 'text', text: 'Use pnpm' }], + content: [{ type: 'text', text: '{"answers":[{"id":"pkg","selected":["pnpm"]}]}' }], }) expect(seen).toMatchObject([{ - question: 'Which package manager should I use?', - options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }], - allowCustom: false, + questions: [{ + id: 'pkg', + question: 'Which package manager should I use?', + options: [{ label: 'pnpm', description: 'Use pnpm workspaces.' }], + }], + }]) + }) + + it('projects custom answers and multi-select choices', async () => { + const ctx = await setup() + ctx.userInteraction.registerProvider({ + async ask() { + return { + answers: [ + { id: 'targets', selected: ['tests', 'docs'] }, + { id: 'notes', selected: [], custom: 'ship today' }, + ], + } + }, + }) + + const result = await ctx.tools.execute({ + callId: CallId('ask-multi'), + name: 'ask_user_question', + arguments: { + questions: [ + { + id: 'targets', + question: 'What should I update?', + options: [{ label: 'tests' }, { label: 'docs' }], + multi_select: true, + }, + { id: 'notes', question: 'Any note?' }, + ], + }, + }) + + expect(result.content).toEqual([{ + type: 'text', + text: '{"answers":[{"id":"targets","selected":["tests","docs"]},{"id":"notes","selected":[],"custom":"ship today"}]}', }]) }) @@ -89,7 +140,7 @@ describe('ask_user_question tool', () => { ctx.userInteraction.registerProvider({ async ask(request) { seen.push(request) - return { answer: 'ok' } + return { answers: [{ id: 'continue', selected: ['ok'] }] } }, }) const controller = new AbortController() @@ -97,7 +148,7 @@ describe('ask_user_question tool', () => { await ctx.tools.execute({ callId: CallId('ask-2'), name: 'ask_user_question', - arguments: { question: 'Continue?' }, + arguments: { questions: [{ id: 'continue', question: 'Continue?' }] }, signal: controller.signal, }) @@ -110,7 +161,7 @@ describe('ask_user_question tool', () => { ctx.userInteraction.registerProvider({ async ask(request) { seen.push(request) - return { answer: 'ok' } + return { answers: [{ id: 'continue', selected: ['ok'] }] } }, }) const agent = { id: 'main' } as unknown as Agent @@ -118,12 +169,12 @@ describe('ask_user_question tool', () => { const result = await ctx.tools.execute({ callId: CallId('ask-3'), name: 'ask_user_question', - arguments: { header: 'Confirm', question: 'Continue?' }, + arguments: { questions: [{ id: 'continue', header: 'Confirm', question: 'Continue?' }] }, agent, }) - expect(result.content).toEqual([{ type: 'text', text: 'ok' }]) - expect(seen[0]).toMatchObject({ header: 'Confirm', agent }) + expect(result.content).toEqual([{ type: 'text', text: '{"answers":[{"id":"continue","selected":["ok"]}]}' }]) + expect(seen[0]).toMatchObject({ questions: [{ id: 'continue', header: 'Confirm', question: 'Continue?' }], agent }) }) it('returns structured user-interaction errors through tool execution', async () => { @@ -132,7 +183,7 @@ describe('ask_user_question tool', () => { const result = await ctx.tools.execute({ callId: CallId('ask-no-provider'), name: 'ask_user_question', - arguments: { question: 'Continue?' }, + arguments: { questions: [{ id: 'continue', question: 'Continue?' }] }, }) expect(result).toMatchObject({ @@ -141,48 +192,19 @@ describe('ask_user_question tool', () => { }) }) - it('uses an option label when the selected option has no explicit value', async () => { + it('returns a structured error for empty question batches', async () => { const ctx = await setup() - ctx.userInteraction.registerProvider({ - async ask(request) { - const option = request.options?.[0] - if (option === undefined) throw new Error('missing option') - return { answer: option.label, option } - }, - }) const result = await ctx.tools.execute({ - callId: CallId('ask-4'), + callId: CallId('ask-empty'), name: 'ask_user_question', - arguments: { - question: 'Pick one', - options: [{ label: 'Fallback label' }], - }, + arguments: { questions: [] }, }) - expect(result.content).toEqual([{ type: 'text', text: 'Fallback label' }]) - }) - - it('returns the provider-computed answer even when option metadata is present', async () => { - const ctx = await setup() - ctx.userInteraction.registerProvider({ - async ask(request) { - const option = request.options?.[0] - if (option === undefined) throw new Error('missing option') - return { answer: `selected ${option.value}`, option } - }, + expect(result).toMatchObject({ + isError: true, + error: { name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' }, }) - - const result = await ctx.tools.execute({ - callId: CallId('ask-5'), - name: 'ask_user_question', - arguments: { - question: 'Pick one', - options: [{ label: 'A', value: 'a' }], - }, - }) - - expect(result.content).toEqual([{ type: 'text', text: 'selected a' }]) }) it('unregisters the tool when its plugin fiber is disposed', async () => { diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index b7062c9e0e..14f2714d95 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -45,7 +45,9 @@ { "doc": "docs/core-data-structures/tools.md", "symbol": "PostToolDecision", "source": "packages/core/tools/src/index.ts" }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionItem", "source": "packages/core/user-interaction/src/index.ts" }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswerItem", "source": "packages/core/user-interaction/src/index.ts" }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/core/user-interaction/src/index.ts" }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/core/user-interaction/src/index.ts" }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/core/user-interaction/src/index.ts" }, From afab88b139717830590fb65b24274aff124203ea Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 7 Jul 2026 16:22:57 +0800 Subject: [PATCH 028/119] docs(rfc): record the schema-validation alternatives considered MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The #192 review discussion, preserved where design rationale lives: a schema-object library (zod/schemastery) cannot sit at a wire-data boundary; ajv replaces only the value walker while the subset gate — the module's point — stays hand-written; provider JSON mode guarantees valid JSON, not schema-conforming JSON, and would trade away mid-run tools and in-turn validation retry for it. Strict tool schemas are named as the accepted upgrade path when the provider ships them. --- docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 7bf09f742c..daf041a1d8 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -56,6 +56,9 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai - **Workflow-layer JSON parsing for `agent({schema})`**: duplicating a seam concern at one consumer while the seam's capability flag stayed dishonestly `false`. - **Meta as tool parameters instead of `export const meta`**: zero parsing, but scripts stop being self-contained artifacts and CC-authored scripts stop being drop-in. - **`SchemaSpec` as the outputSchema type**: the author-facing DSL cannot express what arrives as data and cannot be validated against without conversion loss. +- **A schema-object library (zod, or the repo's schemastery) for the structured-output subset**: the schema is wire data — plain JSON that crosses the vm realm boundary in `agent({schema})` and lands verbatim in the forced tool's parameters — exactly where live schema objects cannot sit; consuming raw JSON Schema at runtime would need a third-party converter on top (zod core only emits JSON Schema, not the reverse), and it would put a second schema language beside schemastery's config role. +- **ajv for value validation**: it validates FULL JSON Schema, so the subset gate — the module's actual point, since every accepted keyword must be one the harness enforces — would remain hand-written regardless; it compiles validators through `new Function`; and it would be dsh-tools' first runtime dependency, all to replace the ~70-line value walker while the path-qualified, every-violation error reporting stays custom either way. +- **Provider JSON mode (`response_format: {type: json_object}`) instead of the forced capture tool**: the official API guarantees valid JSON, not schema-conforming JSON (no `json_schema` type; the docs' own guidance is to validate client-side, with the schema riding in the prompt), so both walkers survive untouched and only the capture-tool mechanics could go — at the cost of tools during a structured child's run (whether `response_format` composes with tool calling is undocumented), the in-turn validation retry (`ToolArgsError` keeps recovery inside the turn; a JSON-mode empty body — a documented failure mode — ends the turn, and the only recovery is the re-prompt loop this design rejects), and a new per-adapter `LlmCallConfig` surface. The accepted upgrade path is strict TOOL schemas (provider-side constrained decoding on tool parameters) when available: the same forced tool and subset gate, with the gate narrowed to the provider's strict subset. ## Consequences From 17bd71e5301b1a396292df3f94d0b6c1aa854068 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 7 Jul 2026 19:42:30 +0800 Subject: [PATCH 029/119] feat(agent): add the agent/request-messages request-only message seam MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A new waterfall near request construction lets plugins contribute request-ONLY messages framing the derived history: RequestMessages { before, after } with a frozen empty seed, fired inside the open step after the agent/request config waterfall, so the step/start boundary snapshot and its same-sync-frame invariant are untouched. The request becomes messagePrefix + boundary snapshot + messageSuffix. Contributions never enter session history — deriveMessages() is unchanged — so the request header is their durable record: EpochHeader gains messagePrefix/messageSuffix (canonical absence for empty arrays), request/header-delta replaces either array whole with an empty array encoding the transition back to absence, and the dev-mode reconstruction cross-check now expects the folded header's framing around the boundary derivation. This is the seam for per-request advisory context that must be model-visible now without becoming durable history (a skills catalog, an environment reminder), keeping the base system prompt workspace-independent and provider prefix caches stable. The docs carry the channel cost model: session-frozen content belongs in before, low-frequency change notices belong in durable history via inject() (paid once, prefix-cached thereafter), and after is reserved for small frequently-refreshed state snapshots re-paid on every request they ride. No shipped producer yet, so ACP snapshot fixtures are byte-identical. --- docs/architecture.md | 19 +-- docs/cordis-catalog/events.md | 40 +++-- docs/core-data-structures/core.md | 42 ++++- docs/core-data-structures/session.md | 30 ++-- docs/event-producer-consumer.md | 23 +-- docs/persistence-catalog.md | 34 ++--- .../2026-07-05-reconstructable-requests.md | 7 +- packages/core/agent-loop/README.md | 6 +- packages/core/agent-loop/src/loop.ts | 43 ++++-- .../agent-loop/tests/interception.spec.ts | 144 +++++++++++++++++- packages/core/agent/README.md | 1 + packages/core/agent/src/types.ts | 94 +++++++++++- packages/core/session/README.md | 2 +- packages/core/session/src/request-header.ts | 52 +++++-- packages/core/session/src/types.ts | 33 ++-- .../core/session/tests/request-header.spec.ts | 51 ++++++- packages/llm/llm/src/types.ts | 6 + packages/support/invariants/src/index.ts | 27 ++-- .../invariants/tests/invariants.spec.ts | 16 ++ scripts/type-equiv.manifest.json | 2 + 20 files changed, 553 insertions(+), 119 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 371b5df579..18138c41cd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,14 +1,14 @@ # DeepSeek Harness Architecture -The **DeepSeek Harness SDK** is an SDK for building agent harnesses using the Cordis framework. The governing principle is simple: **everything is a plugin**. For example, the shipped agent loop is just one plugin in the default bundle, not a privileged kernel. +The **DeepSeek Harness SDK** is an SDK for building agent harnesses on the Cordis framework. The governing principle is simple: **everything is a plugin**. The shipped agent loop is one plugin in the default bundle, not a privileged kernel. -Read this page as the system map before changing `packages/`. It explains how the runtime is shaped, how the default loop moves work, where state lives, and where extensions attach. Type shapes live in [core-data-structures/](core-data-structures/core.md); exact event and service signatures live in the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs; package contracts live in the [package map](../packages/README.md); rationale lives in the [RFCs](rfc/README.md). If Cordis itself is new to you, start with the [Cordis primer](cordis-primer.md). +Read this page as the system map before changing `packages/`. It explains how the runtime is shaped, how the default loop moves work, where state lives, and where extensions attach. Type shapes live in [core-data-structures/](core-data-structures/core.md); exact event and service signatures live in the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs; package contracts live in the [package map](../packages/README.md); rationale lives in the [RFCs](rfc/README.md). New to Cordis? Start with the [Cordis primer](cordis-primer.md). ## System Shape A running harness is one Cordis context. Packages contribute service keys, typed events, and disposable registrations to that context. Services are the stable call surfaces (`ctx.llm`, `ctx.tools`, `ctx.sessions`); events are interception and notification points (`agent/request`, `tools/pre-execute`, `session/event`); registrations install prompt sections, tool schemas, providers, adapters, and listeners. -The default distribution is a composition, not a hierarchy. `packages/core/` is a repository grouping for the default agent spine; capability seams around it are equally first-class plugins from a Cordis perspective. +The default distribution is a composition, not a hierarchy. `packages/core/` is a repository grouping for the default agent spine; capability seams around it are equally first-class plugins. ### Default Service Spine @@ -46,11 +46,11 @@ Use the event domain to decide where new behavior belongs: ### Interception Semantics -Waterfall events behave like around-middleware: a listener delegates by calling `next()` and vetoes or takes over by returning without it. The full rule lives in [Cordis waterfall semantics](cordis-primer.md#cordis-waterfall-semantics). +Waterfall events behave like around-middleware: a listener delegates by calling `next()` and vetoes or takes over by returning without it. Full rule: [Cordis waterfall semantics](cordis-primer.md#cordis-waterfall-semantics). ## Default Loop Lifecycle -The shipped loop drains queued work, assembles a request, streams a model answer, executes tools, decides whether to continue, and checkpoints durable state. The important architecture is where it pauses: each pause is a documented service call or event seam that another plugin can program against. +The shipped loop drains queued work, assembles a request, streams a model answer, executes tools, decides whether to continue, and checkpoints durable state. The important architecture is where it pauses: each pause is a documented service call or event seam other plugins program against. A **session** is one agent's append-only event log. A **turn** drains one queued batch and runs until the model stops asking for tools and no plugin requests continuation. A **step** is one model request plus the tool executions caused by that response. In the flow below ([sequence companion](agent-lifecycle.md)), quoted names are durable session events and event names are extension seams. @@ -72,7 +72,7 @@ forever: agent/pre-step 'step/start' snapshot the derived messages (the reconstruction boundary) - agent/request (config only) -> log request/header -> llm/stream (frozen) + agent/request (config only) -> agent/request-messages -> log request/header -> llm/stream (frozen) 'assistant/chunk' agent/step-result 'assistant/message' @@ -88,7 +88,7 @@ forever: checkpoint persistence and notify idle/running status ``` -Prompt assembly is single-path: `renderPrompt(assemble({ agent }))` IS the system prompt sent to the model. Plugins contribute ordered sections (static or computed from the per-call `AssembleContext`), tool schemas, and named variables interpolated as `{{name}}` at render — strictly, so an unknown or valueless reference fails the turn instead of shipping a hole. `dsh-system-prompt` itself owns the openers — the static `harness:identity` section (order −100) and the deployment's persona (order 0, from its `persona` config, shared by every agent in the context) — while the shipped loop registers the `model`/`cwd` variables; prompt-fact ownership is pinned by the [prompt-variables RFC](rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md). +Prompt assembly is single-path: `renderPrompt(assemble({ agent }))` IS the system prompt sent to the model. Plugins contribute ordered sections (static or computed from the per-call `AssembleContext`), tool schemas, and named variables interpolated as `{{name}}` at render — strictly, so an unknown or valueless reference fails the turn instead of shipping a hole. `dsh-system-prompt` owns the openers — the static `harness:identity` section (order −100) and the deployment's persona (order 0, its `persona` config, shared context-wide) — while the shipped loop registers the `model`/`cwd` variables; prompt-fact ownership is pinned by the [prompt-variables 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; leftover steering after a turn is re-queued as ordinary input. @@ -108,7 +108,7 @@ Every session event is turn-enclosed. Reloading a crashed session preserves the The session log is the source of truth. `deriveMessages()` projects session events into the `Message[]` sent to the model; raw `assistant/chunk` events stay in the log for replay and UI fidelity. Replay, fork, resume, transcript rendering, telemetry, and persistence all derive from the same event stream. -**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start`, headers by folding `request/header` — and dev invariants assert this ([reconstructability RFC](rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). +**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` framed by the header's request-only `messagePrefix`/`messageSuffix`, headers by folding `request/header` — and dev invariants assert this ([reconstructability RFC](rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). Durability is a plugin concern. Persistence backends buffer synchronous `session/event` notifications and the loop awaits a turn-end checkpoint before moving on. The `SessionPersistence` seam stores `SessionEvent` directly, with metadata in `SessionHeader`; JSONL and SQLite share one contract suite. @@ -122,7 +122,7 @@ Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAs ### Capability Pattern -A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and vocabulary; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability seam graph](capability-seams.md) shows the current package families. +A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and vocabulary; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability seam graph](capability-seams.md) shows the package families. Some seams bend the template deliberately. LLM keeps interface and consumer vocabulary together because adapters are the implementations. Filesystem adds policy as event gates around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Subagents use a named provider registry because multiple delegation backends can coexist; `spawn` starts fresh, `fork` seeds from the parent's completed-turn prefix, and ACP can drive an out-of-process child ([subagent.md](core-data-structures/subagent.md)). @@ -141,6 +141,7 @@ New behavior should attach to a documented seam; changing the shipped loop requi | Add command execution | implement and register a `ctx.bash` backend | | Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events | | Intercept prompts, requests, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` waterfall | +| Add per-request context that must not become history | contribute request-only messages on `agent/request-messages`; logged on the request header | | Add UI or editor integration | drive `ctx.agents` and render from `session/event` | | Add durable session state | add a `SessionEventMap` member and render/replay from the log | | Fork a live session | use `ctx.sessions.fork(source, boundary?, childSessionId?)` | diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 753cf8f4d0..d62e1ef042 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -23,7 +23,7 @@ An agent was registered in the AgentRegistry and is ready to receive messages. Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:248`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:292`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -35,7 +35,7 @@ An agent was disposed and removed from the registry; its fiber and any in-flight Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:255`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:299`](../../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:404`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:490`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -61,7 +61,7 @@ Serial (awaited in registration order), not a waterfall: a listener mutates the Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:333`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:377`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -73,7 +73,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a 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:346`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:390`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -85,11 +85,11 @@ A message entered the agent's inbox (queued or steering). `source` is the resolv 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:273`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:317`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall -Waterfall: shape the step's call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use). Config is ALL a listener shapes here: every request is a pure function of the session log (the reconstructability RFC), so model-visible content flows through the log channels — `inject()`, steering, prompt-submit `additionalContext`, prompt sections via `system-prompt/assemble` — never through request mutation, and the loop records whatever config the request actually uses as a `request/header*` event before dispatch. The step's messages are already snapshotted when this fires (the `step/start` boundary): an `inject()` from a listener here lands in the log but joins the NEXT request. For surface mutation that must precede the snapshot (compaction), use agent/pre-step. Call `next()` to delegate, or return an LlmCallConfig without it to short-circuit. +Waterfall: shape the step's call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use). Config is ALL a listener shapes here: every request is a pure function of the session log (the reconstructability RFC), so model-visible content flows through the log channels — `inject()`, steering, prompt-submit `additionalContext`, prompt sections via `system-prompt/assemble`, or header-logged request-only messages via agent/request-messages — never through request mutation, and the loop records whatever config the request actually uses as a `request/header*` event before dispatch. The step's messages are already snapshotted when this fires (the `step/start` boundary): an `inject()` from a listener here lands in the log but joins the NEXT request. For surface mutation that must precede the snapshot (compaction), use agent/pre-step. Call `next()` to delegate, or return an LlmCallConfig without it to short-circuit. ```ts cordis-catalog 'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise @@ -97,7 +97,23 @@ Waterfall: shape the step's call configuration — model switching, sampling ove Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:369`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:414`](../../packages/core/agent/src/types.ts) + +### `agent/request-messages` — waterfall + +Waterfall: contribute request-ONLY messages around the derived history — a RequestMessages whose `before` messages precede the boundary snapshot in `GenerateOptions.messages` and whose `after` messages follow it. Fires once per step, inside the open step, after the agent/request config waterfall and before the loop logs the request header. This is the seam for per-request advisory context the model must see NOW but that must NOT become durable history (a skills catalog, an environment reminder): contributions are recorded on the request's `request/header*` event (`EpochHeader.messagePrefix` / `messageSuffix`) — never as session messages — so `Session.deriveMessages()` stays untouched and the request remains reconstructable from the log. + +The seed is frozen and empty; a contributing listener returns a NEW RequestMessages extending `await next()` (spread its arrays — never mutate them), so contributions compose across plugins in registration order. The boundary snapshot is already taken when this fires: a `session.append`/`inject()` from a listener here lands in the log but joins the NEXT request — contribute through the returned value, not the session. Call `next()` to delegate, or return a RequestMessages without it to short-circuit. + +Pick the channel by change frequency (the cost model): a contribution rides the request's uncached tail, re-tokenized at full price on EVERY request it appears in — cheap only while small. Session-FROZEN content belongs in `before`, where it extends the cacheable prefix at zero marginal cost (but changing it mid-session invalidates the provider cache for the entire history after it). A LOW-FREQUENCY change notice belongs in durable history via `agent.inject()` — appended once, prefix-cached thereafter. Reserve `after` for small, frequently refreshed state snapshots, where a durable chain of stale copies would bloat the log and mislead the model. + +```ts cordis-catalog +'agent/request-messages'(agent: Agent, turn: number, step: number, messages: RequestMessages, context: RequestMessagesContext, next: () => Promise): Promise +``` + +Types: [Agent](../core-data-structures/core.md) + +Source: [`packages/core/agent/src/types.ts:455`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -109,7 +125,7 @@ The agent's session lifecycle began, fired once before its first turn. `source` Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:288`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:332`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -121,7 +137,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle Types: [Agent](../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:308`](../../packages/core/agent/src/types.ts) ### `agent/step-result` — waterfall @@ -133,7 +149,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:379`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:465`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -145,7 +161,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:392`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:478`](../../packages/core/agent/src/types.ts) ## `fs/*` diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 8cd9f1c30b..62dfb41c64 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -127,6 +127,12 @@ Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts) ```ts type-equiv interface GenerateOptions { model: string + /** + * Ordered conversation messages, exactly as the provider sees them (after + * the `system` slot). A loop-built request assembles them as + * `EpochHeader.messagePrefix` + the derived history + `messageSuffix` + * (dsh-agent-loop); a hand-built one-shot passes any list. + */ messages: Message[] /** System prompt text (adapters map to the provider's system slot). */ system?: string @@ -187,7 +193,9 @@ The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` ### The request envelope: `LlmCallConfig` and the logged header -Requests are built by the loop, not shaped per call: the non-content half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt and assembled tool schemas — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws. +Requests are built by the loop, not shaped per call: the non-history half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt, assembled tool schemas, and any request-only messages — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling; the `agent/request-messages` waterfall contributes request-only messages framing the derived history (recorded as the header's `messagePrefix`/`messageSuffix`) — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws. + +On the wire, a loop-built request reads in this order: the `system` slot (the rendered prompt assembly) → `messagePrefix` (request-only `before` contributions) → the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps — → `messageSuffix` (request-only `after` contributions, the last thing the model reads). The framing arrays never enter the derived history; their durable record is the header events, and the dev invariant recomputes exactly this equation against every loop-built request. FIXME(call-config-shape): revisit the exact definition of this type — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit here out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them. @@ -320,7 +328,7 @@ interface Agent { } ``` -`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`) is merge-extensible — plugins add creation options by declaration merging; the persona is NOT an agent option but the `dsh-system-prompt` plugin's `persona` config, shared context-wide. The `agent/*` event taxonomy (lifecycle emits incl. `agent/session-start`, the serial `agent/pre-step` surface-mutation seam, and the `agent/prompt-submit`/`agent/request`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy); turn/step boundaries are durable `session/event` records, not `agent/*` emits. +`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`) is merge-extensible — plugins add creation options by declaration merging; the persona is NOT an agent option but the `dsh-system-prompt` plugin's `persona` config, shared context-wide. The `agent/*` event taxonomy (lifecycle emits incl. `agent/session-start`, the serial `agent/pre-step` surface-mutation seam, and the `agent/prompt-submit`/`agent/request`/`agent/request-messages`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy); turn/step boundaries are durable `session/event` records, not `agent/*` emits. ## Interception decisions @@ -357,6 +365,36 @@ type ContinuationDecision = type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact' ``` +`agent/request-messages` returns a `RequestMessages` — request-only `before`/`after` messages framing the derived history for ONE request. Not a Decision union: the seam contributes content instead of vetoing, so the shape is the contribution itself; the loop records the non-empty arrays as the header's `messagePrefix`/`messageSuffix` ([the request envelope](#the-request-envelope-llmcallconfig-and-the-logged-header)), and `deriveMessages()` never returns them: + +```ts type-equiv +interface RequestMessages { + /** Messages placed before the derived history in the request. */ + before: Message[] + /** Messages placed after the derived history in the request. */ + after: Message[] +} +``` + +Listeners read the already-fixed request facts from a `RequestMessagesContext` (decide what to contribute from these; never mutate them): + +```ts type-equiv +interface RequestMessagesContext { + /** The rendered system prompt this request will carry. */ + system: string + /** The prompt assembly the system prompt was rendered from (sections + tools). */ + assembly: PromptAssembly + /** + * The boundary snapshot: the derived history this request will carry between + * `before` and `after`. A frozen snapshot — treat it as read-only; content + * for the NEXT request flows through the log channels. + */ + boundaryMessages: readonly Message[] + /** Aborts in-flight listener work when the step is torn down. */ + signal: AbortSignal +} +``` + ## `ToolDefinition` The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional UI presenters. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through. diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index 6c4712114f..ddfa77a9ff 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -74,16 +74,15 @@ interface SessionEventMap { */ 'request/header': { header: EpochHeader; reason: RequestHeaderReason } /** - * Amendment to the folded {@link EpochHeader}: at least one of a - * {@link SystemDelta}, a {@link ToolsDelta}, or a whole replacement - * {@link LlmCallConfig} (four scalars — not worth diffing). Appended by the - * loop inside the step, before dispatch, when the header for this request - * differs from the fold of the log so far; the writer verifies - * `applyHeaderDelta(previous, delta)` reproduces the new header exactly and - * falls back to a `'fallback'` `request/header` snapshot when it cannot, so - * a logged delta ALWAYS round-trips. NOT a {@link SurfaceEventType}. + * Amendment to the folded {@link EpochHeader}: system line-trim, name-keyed + * tools delta, whole replacement config, or whole replacement request-only + * message arrays (an EMPTY array encodes the transition to "none"). The + * writer verifies `applyHeaderDelta(previous, delta)` reproduces the new + * header exactly and falls back to a `'fallback'` `request/header` snapshot + * when it cannot, so a logged delta ALWAYS round-trips. NOT a + * {@link SurfaceEventType}. */ - 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } + 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[]; messageSuffix?: Message[] } } ``` @@ -100,7 +99,7 @@ export interface TodoItem { ### The request header events: `request/header` and `request/header-delta` -The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A `request/header` snapshot (reason `'initial' | 'resume' | 'fallback'`) anchors the fold at conversation birth, process boundaries, and delta-encoding fallbacks; `request/header-delta` events amend it mid-run. `foldRequestHeader(events)` reconstructs the header any request was built under; the writer round-trip-verifies every delta before logging it, so a well-formed log always folds. Neither is a `SurfaceEventType` — they produce no LLM message. +The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas + request-only messages) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A `request/header` snapshot (reason `'initial' | 'resume' | 'fallback'`) anchors the fold at conversation birth, process boundaries, and delta-encoding fallbacks; `request/header-delta` events amend it mid-run. `foldRequestHeader(events)` reconstructs the header any request was built under; the writer round-trip-verifies every delta before logging it, so a well-formed log always folds. Neither is a `SurfaceEventType` — they produce no LLM message. ```ts type-equiv export interface EpochHeader { @@ -110,10 +109,19 @@ export interface EpochHeader { system?: string /** Assembled tool schemas; absent for a tool-less request. */ tools?: ToolSchema[] + /** + * Request-only messages sent BEFORE the derived history (the + * `agent/request-messages` waterfall's `before` contributions). Not session + * history — `deriveMessages()` never returns them — so the header is their + * only durable record; absent when the request carried none. + */ + messagePrefix?: Message[] + /** Request-only messages sent AFTER the derived history; absent when none. */ + messageSuffix?: Message[] } ``` -Canonical form: an empty system prompt and an empty tool list are ABSENT fields, matching how requests are built. The delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). +Canonical form: an empty system prompt, an empty tool list, and empty request-only message arrays are ABSENT fields, matching how requests are built. `messagePrefix`/`messageSuffix` are the durable record of the `agent/request-messages` waterfall's contributions (the request is `messagePrefix + derived history + messageSuffix`); their deltas replace the array whole, an empty array encoding the transition back to absence. The other delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). ## `SessionEvent` — one log entry diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 24a2793826..44bbe79144 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -7,17 +7,18 @@ 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:248`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:255`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:404`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:346`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:273`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:369`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:288`](../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:264`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:379`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:392`](../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/created` | `emit` | [`packages/core/agent/src/types.ts:292`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:299`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:490`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:377`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:390`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:317`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:414`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/request-messages` | `waterfall` | [`packages/core/agent/src/types.ts:455`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:332`](../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:308`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:465`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:478`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../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:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index c29cbc0d99..b3618d93f8 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -23,7 +23,7 @@ Raw stream chunk — token-level replay fidelity. Types: [StreamChunk](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:298`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:309`](../packages/core/session/src/types.ts) #### `assistant/message` — surface @@ -35,7 +35,7 @@ Assembled assistant message for one step (derived history uses this). Carries th Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:305`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:316`](../packages/core/session/src/types.ts) ### `compact/*` @@ -83,7 +83,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:307`](../packages/core/session/src/types.ts) ### `hook/*` @@ -119,7 +119,7 @@ A queued prompt an `agent/prompt-submit` listener VETOED — the durable record Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:301`](../packages/core/session/src/types.ts) ### `request/*` @@ -131,17 +131,17 @@ Full snapshot of the EpochHeader the NEXT request is built under, with the Reque 'request/header': { header: EpochHeader; reason: RequestHeaderReason } ``` -Source: [`packages/core/session/src/types.ts:350`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:361`](../packages/core/session/src/types.ts) #### `request/header-delta` — log-only -Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta, or a whole replacement LlmCallConfig (four scalars — not worth diffing). Appended by the loop inside the step, before dispatch, when the header for this request differs from the fold of the log so far; the writer verifies `applyHeaderDelta(previous, delta)` reproduces the new header exactly and falls back to a `'fallback'` `request/header` snapshot when it cannot, so a logged delta ALWAYS round-trips. NOT a SurfaceEventType. +Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta, a whole replacement LlmCallConfig (four scalars — not worth diffing), or a whole replacement request-only message array (`messagePrefix`/`messageSuffix` — small advisory content, replaced whole; an EMPTY array encodes the transition to "none", mirroring the canonical form's absent field). Appended by the loop inside the step, before dispatch, when the header for this request differs from the fold of the log so far; the writer verifies `applyHeaderDelta(previous, delta)` reproduces the new header exactly and falls back to a `'fallback'` `request/header` snapshot when it cannot, so a logged delta ALWAYS round-trips. NOT a SurfaceEventType. ```ts persistence-catalog -'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } +'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[]; messageSuffix?: Message[] } ``` -Source: [`packages/core/session/src/types.ts:361`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:376`](../packages/core/session/src/types.ts) ### `steering/*` @@ -155,7 +155,7 @@ Steering content injected between steps of a running turn. Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:323`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:334`](../packages/core/session/src/types.ts) ### `step/*` @@ -167,7 +167,7 @@ Closes step `step` of turn `turn`. 'step/end': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:288`](../packages/core/session/src/types.ts) #### `step/start` — log-only @@ -177,7 +177,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it 'step/start': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:286`](../packages/core/session/src/types.ts) ### `todo/*` @@ -193,7 +193,7 @@ NOT a SurfaceEventType: it produces no LLM message and never reaches `deriveMess Types: [TodoItem](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:337`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:348`](../packages/core/session/src/types.ts) ### `tool/*` @@ -207,7 +207,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st Types: [CallId](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:311`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:322`](../packages/core/session/src/types.ts) #### `tool/result` — surface @@ -219,7 +219,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:321`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:332`](../packages/core/session/src/types.ts) ### `turn/*` @@ -233,7 +233,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai Types: [TurnEndReason](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:273`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:284`](../packages/core/session/src/types.ts) #### `turn/start` — log-only @@ -245,7 +245,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch Types: [TurnTrigger](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:267`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:278`](../packages/core/session/src/types.ts) ### `user/*` @@ -259,4 +259,4 @@ A user-visible prompt (queued message drained at turn start). Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts) diff --git a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md index 601e64f70a..e17679f913 100644 --- a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -20,13 +20,13 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro **Messages.** `Session.deriveMessages()` is cached: each surface node is projected exactly once, when first seen, through the public per-node function `deriveEventMessage(event)`; a surface rewrite (a compaction `replace` — `SurfaceManager.replaceGeneration`) rebuilds. Callers get a fresh array per call over shared, deep-frozen messages: mutating logged history through a projection is unrepresentable (it throws), replacing the old clone-per-call isolation. External reconstructors fold the same public function over a log prefix, so no two paths can disagree. -**The header.** The request's non-content half — `EpochHeader`: call config (`LlmCallConfig`: model + sampling scalars), rendered system prompt, assembled tool schemas — is logged session state, in canonical form (empty system/tools ≡ absent). Two log-only, turn-enclosed events in dsh-session carry it: `request/header`, a full snapshot with reason `'initial' | 'resume' | 'fallback'`, and `request/header-delta`, an amendment (`SystemDelta`: a common-prefix/suffix line trim; `ToolsDelta`: name-keyed added/removed/changed; `config`: replaced whole). The pure trio `foldRequestHeader` / `diffHeader` / `applyHeaderDelta` reconstructs; the live session tracks the fold with the same lazy cursor as the message cache. Snapshots anchor the fold where a fold needs anchors — conversation birth and process boundaries — and each loop instance appends one on its first request (`'initial'` when the log has none, `'resume'` otherwise, even when nothing changed: the boundary itself is a recorded fact, and cross-restart drift becomes attributable while an unchanged header resumes byte-identical). Deltas are an encoding optimization with a safety valve, never a correctness dependency: the writer verifies `applyHeaderDelta(prev, delta)` reproduces the new header exactly and records a `'fallback'` snapshot when the encoding cannot express a change (a pure tool reordering), so a well-formed log always folds. +**The header.** The request's non-history half — `EpochHeader`: call config (`LlmCallConfig`: model + sampling scalars), rendered system prompt, assembled tool schemas, and any request-only messages (`messagePrefix`/`messageSuffix`, below) — is logged session state, in canonical form (empty system/tools/message arrays ≡ absent). Two log-only, turn-enclosed events in dsh-session carry it: `request/header`, a full snapshot with reason `'initial' | 'resume' | 'fallback'`, and `request/header-delta`, an amendment (`SystemDelta`: a common-prefix/suffix line trim; `ToolsDelta`: name-keyed added/removed/changed; `config`: replaced whole; `messagePrefix`/`messageSuffix`: replaced whole, an empty array encoding the transition to absence). The pure trio `foldRequestHeader` / `diffHeader` / `applyHeaderDelta` reconstructs; the live session tracks the fold with the same lazy cursor as the message cache. Snapshots anchor the fold where a fold needs anchors — conversation birth and process boundaries — and each loop instance appends one on its first request (`'initial'` when the log has none, `'resume'` otherwise, even when nothing changed: the boundary itself is a recorded fact, and cross-restart drift becomes attributable while an unchanged header resumes byte-identical). Deltas are an encoding optimization with a safety valve, never a correctness dependency: the writer verifies `applyHeaderDelta(prev, delta)` reproduces the new header exactly and records a `'fallback'` snapshot when the encoding cannot express a change (a pure tool reordering), so a well-formed log always folds. -**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → the header event the request owes the log → build `GenerateOptions` from the snapshot + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's only in-process bookkeeping is one boolean: whether this instance has logged its anchoring snapshot. +**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → the `agent/request-messages` waterfall — request-ONLY `before`/`after` messages framing the boundary snapshot (a frozen empty seed, contributions returned as an extension of `next()`; the per-request advisory channel: content the model must see now that must NOT become history — a skills catalog, an environment reminder) — → the header event the request owes the log, carrying those contributions as `messagePrefix`/`messageSuffix` (no session event carries them, so the header is their only durable record) → build `GenerateOptions` from `messagePrefix + snapshot + messageSuffix` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's only in-process bookkeeping is one boolean: whether this instance has logged its anchoring snapshot. **The reconstruction boundary is `step/start`, unconditionally.** A step's messages are the derivation over `events[0..stepStartSeq)`. Because the snapshot precedes the `step/start` append in the same synchronous frame, nothing can enter this request past the boundary: an `agent.inject()` from an `agent/request` listener (or any concurrent task, or a `session/event` listener firing on `step/start` itself) lands in the log after the boundary and joins the NEXT request. For waterfall-window appends this matches the prior loop (it also derived before its waterfall); for a synchronous `step/start` listener it is a deliberate change — such a listener could previously reach the current request — and `agent/pre-step` is the sanctioned seam for content that must affect the CURRENT request. A step's header for reconstruction is the fold after its own `request/header*` event (which sits between its `step/start` and first response event) or the fold carried forward. -**Enforcement.** Dev-mode ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)), on `llm/stream`: a frozen request with a live `sessionId` — the loop-built marker; hand-built one-shots are unfrozen and skipped — must carry messages deep-equal to the boundary derivation, rebuilt through a FRESH `Session` over `events[0..stepStartSeq)` so the live cache cannot vouch for itself, and header fields equal to `foldRequestHeader` over the log. There is no divergence allowance and nothing to allow: no seam can put unlogged content into a request. `prepend: true` only defends against the replay adapter's short-circuit (an append-registered listener); two prepended listeners have no defined mutual order in cordis, so correctness rests on the seq-bounded fold, never on listener timing. Measurement stays lean: the with-key e2e ([request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts)) proves `usage.cacheReadTokens > 0` on every request after the first against the live API, and per-step usage in the log is the production observable — a header event or compaction shows up as a cache-read collapse on the next step. +**Enforcement.** Dev-mode ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)), on `llm/stream`: a frozen request with a live `sessionId` — the loop-built marker; hand-built one-shots are unfrozen and skipped — must carry messages deep-equal to the folded header's `messagePrefix`, then the boundary derivation, then its `messageSuffix` — the derivation rebuilt through a FRESH `Session` over `events[0..stepStartSeq)` so the live cache cannot vouch for itself — and header fields equal to `foldRequestHeader` over the log. There is no divergence allowance and nothing to allow: no seam can put unlogged content into a request — the `agent/request-messages` seam's contributions enter only because the header event records them first. `prepend: true` only defends against the replay adapter's short-circuit (an append-registered listener); two prepended listeners have no defined mutual order in cordis, so correctness rests on the seq-bounded fold, never on listener timing. Measurement stays lean: the with-key e2e ([request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts)) proves `usage.cacheReadTokens > 0` on every request after the first against the live API, and per-step usage in the log is the production observable — a header event or compaction shows up as a cache-read collapse on the next step. ### The MiniCode shape: adopted, with the provenance arrow inverted @@ -44,6 +44,7 @@ What survives from `LLMClient`: the conversation is maintained, not rebuilt — ## Consequences - A request that is not explained by the log cannot be constructed by accident — not by the loop, not by a listener; mutating a built request throws; every header change is a durable, diffable log event. +- Choosing between the advisory channels is a change-frequency cost decision, and the seam does not hide it: an `agent/request-messages` contribution rides the request's uncached tail and is re-tokenized at full price on every request it appears in (a `before` contribution instead extends the cacheable prefix at zero marginal cost while stable, but a mid-session change invalidates the provider cache for the entire history after it), whereas an `inject()`ed `context/message` is paid once and prefix-cached thereafter at the price of accumulating durably in history and the log. Route session-frozen content to `before`, low-frequency change notices to `inject()`, and reserve `after` for small, frequently refreshed state snapshots where a durable chain of stale copies would bloat the log and mislead the model. - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replace node), a real prompt/tool change (`request/header-delta`), a config switch (ditto), a process boundary with drift (`'resume'` snapshot differing from its predecessor). The provider's own reasoning-content exclusion is managed server-side. - The `step/start`-listener behavior change (above) is the one observable semantics change for plugins; `agent/pre-step` is the current-request seam. - Tool-result trimming (planned) needs no new mechanism: a logged single-node surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic. diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index ed651ca7f0..2afa08850a 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -59,8 +59,10 @@ forever: boundary = session.deriveMessages() ⟵ reconstruction boundary: same sync frame, session('step/start') strictly before step/start config = waterfall agent/request ⟵ frozen seed; return a replacement to switch + reqMsgs = waterfall agent/request-messages ⟵ request-only before/after messages; recorded + on the header, never session history session('request/header'[-delta]) ⟵ the header event this request owes the log - stream llm.stream(freeze({header..., messages: boundary})) → session('assistant/chunk') + stream llm.stream(freeze({header..., messages: before+boundary+after})) → session('assistant/chunk') message = waterfall agent/step-result session('assistant/message') each tool-call: session('tool/call') @@ -84,7 +86,7 @@ Cancellation: `agent.cancel()` is the single public stop primitive — it clears ### What is NOT here Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy: -- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` +- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/request-messages`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` - Compaction: `agent/pre-step` - Sandbox, permission, plan mode: `tools/pre-execute` (deny/ask gate), `tools/post-execute` - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred. diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index 9484f0ad5f..600bb211a1 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -10,7 +10,7 @@ import type { Context } from 'cordis' import type { FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm' import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm' -import type { ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent' +import type { ContinuationDecision, HookContext, PromptDecision, RequestMessages } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session' import { createTransmissionLog, recordRequestHeader } from './request-log.ts' @@ -161,9 +161,11 @@ export interface LoopHandle { * boundary = session.deriveMessages() ⟵ the reconstruction boundary: snapshot in the * session('step/start') same sync frame, strictly before step/start * config = waterfall agent/request(config) ⟵ frozen seed; a returned replacement switches + * reqMsgs = waterfall agent/request-messages ⟵ request-only before/after messages; logged on + * the header, never session history * session('request/header'|'request/header-delta') ⟵ the header event this request owes the * log (initial/resume anchor, delta, fallback) - * req = freeze({header..., messages: boundary, sessionId, signal}) + * req = freeze({header..., messages: before+boundary+after, sessionId, signal}) * stream ctx.llm.stream(req) ⟵ waterfall llm/stream (raw chunks, frozen req) * session('assistant/chunk') * msg = waterfall agent/step-result ⟵ BEFORE the log append, so the @@ -671,11 +673,11 @@ function drainSteering(agent: ReactLoopAgent, turn: number): boolean { } /** One step: build the request from the boundary snapshot + the step's - * header → log the header event the request owes → stream model → record → - * execute tools. The caller assembles the system prompt, fires the - * `agent/pre-step` seam, snapshots the derivation, and opens the step BEFORE - * calling this, so `boundaryMessages` is exactly the surface prefix at - * step/start and already reflects any compaction. */ + * header → collect request-only messages → log the header event the request + * owes → stream model → record → execute tools. The caller assembles the + * system prompt, fires the `agent/pre-step` seam, snapshots the derivation, + * and opens the step BEFORE calling this, so `boundaryMessages` is exactly + * the surface prefix at step/start and already reflects any compaction. */ async function runStep( ctx: Context, agent: ReactLoopAgent, @@ -715,22 +717,43 @@ async function runStep( throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`) } + // Collect request-ONLY messages: `before` contributions precede the boundary + // snapshot in the request, `after` contributions follow it. They are not + // session history — the header event below is their only durable record + // (EpochHeader.messagePrefix/messageSuffix), which keeps the request a pure + // function of the log. The frozen empty seed serves both the listener chain + // and the no-listener fallback: a contribution is a RETURNED extension of + // `await next()`, never an in-place push. Fired AFTER the boundary snapshot, + // so a listener's session append lands past the boundary and joins the NEXT + // request — the same window rule as the `agent/request` waterfall. + const emptyRequestMessages: RequestMessages = deepFreeze({ before: [], after: [] }) + const requestMessages = await ctx.waterfall( + 'agent/request-messages', agent, turn, step, emptyRequestMessages, + { system, assembly, boundaryMessages, signal }, + () => Promise.resolve(emptyRequestMessages), + ) + // The request header (the log's request/header* vocabulary): canonical form, - // recorded before dispatch so the log always explains the request. + // recorded before dispatch so the log always explains the request — + // including the request-only messages, which no other event carries. const header = canonicalHeader({ config, ...system ? { system } : {}, ...assembly.tools.length > 0 ? { tools: assembly.tools } : {}, + ...requestMessages.before.length > 0 ? { messagePrefix: requestMessages.before } : {}, + ...requestMessages.after.length > 0 ? { messageSuffix: requestMessages.after } : {}, }) recordRequestHeader(session, transmission, header) // Build and freeze: the request is a pure function of (boundary snapshot, // logged header) — llm/stream listeners and adapters read it, mutation // throws. sessionId + frozen is the loop-built marker the dev invariant - // keys on. + // keys on. Message order: header.messagePrefix, then the boundary snapshot, + // then header.messageSuffix — the reconstruction equation the invariant + // recomputes. const request: GenerateOptions = deepFreeze({ model: header.config.model, - messages: boundaryMessages, + messages: [...header.messagePrefix ?? [], ...boundaryMessages, ...header.messageSuffix ?? []], ...header.system !== undefined ? { system: header.system } : {}, ...header.tools !== undefined ? { tools: header.tools } : {}, ...header.config.temperature !== undefined ? { temperature: header.config.temperature } : {}, diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index e76ac30fa9..36b9100b85 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -1,13 +1,14 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import LlmService, { CallId } from '@deepseek-ai/dsh-llm' -import SessionStore, { type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' +import LlmService, { CallId, type Message } from '@deepseek-ai/dsh-llm' +import SessionStore, { foldRequestHeader, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools' import AgentRegistry, { AgentId, type ContinuationDecision, type PromptDecision, + type RequestMessages, type SessionStartSource, } from '@deepseek-ai/dsh-agent' import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' @@ -310,6 +311,145 @@ describe('agent/session-start', () => { }) }) +describe('agent/request-messages (RequestMessages)', () => { + it('frames the derived history: before precedes it, after follows it, and the header records both', async () => { + const adapter = new MockAdapter([textResponse('ok')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'catalog' }] } + const trailer: Message = { role: 'user', content: [{ type: 'text', text: 'trailing note' }] } + ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next): Promise => { + const result = await next() + return { before: [...result.before, reminder], after: [...result.after, trailer] } + }) + + send(agent, 'hi') + await waitForIdle(ctx, agent) + + // The request carries before + derived history + after, in that order… + const request = adapter.requests[0]! + expect(request.messages).toEqual([ + reminder, + { role: 'user', content: [{ type: 'text', text: 'hi' }] }, + trailer, + ]) + // …the header event is their durable record… + const headerEvent = events(agent).find(e => e.type === 'request/header') + expect(headerEvent?.type === 'request/header' && headerEvent.data.header.messagePrefix).toEqual([reminder]) + expect(headerEvent?.type === 'request/header' && headerEvent.data.header.messageSuffix).toEqual([trailer]) + // …and they never become session history. + expect(agent.session.deriveMessages()).toEqual([ + { role: 'user', content: [{ type: 'text', text: 'hi' }] }, + { role: 'assistant', content: [{ type: 'text', text: 'ok' }] }, + ]) + }) + + it('contributions compose across listeners and see the read-only request facts', async () => { + const adapter = new MockAdapter([textResponse('ok')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + const seen: { system: string; boundaryRoles: string[]; sectionCount: number }[] = [] + ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, context, next): Promise => { + const result = await next() + seen.push({ + system: context.system, + boundaryRoles: context.boundaryMessages.map(m => m.role), + sectionCount: context.assembly.sections.length, + }) + return { before: [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...result.before], after: result.after } + }) + ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next): Promise => { + const result = await next() + return { before: [...result.before, { role: 'user', content: [{ type: 'text', text: 'second' }] }], after: result.after } + }) + + send(agent, 'hi') + await waitForIdle(ctx, agent) + + // Registration order composes: the first listener runs last on the way + // out (waterfall), so its prepend lands first. + const texts = adapter.requests[0]!.messages.map(m => m.content[0]?.type === 'text' ? m.content[0].text : '') + expect(texts).toEqual(['first', 'second', 'hi']) + // The context carried the request facts: the rendered system prompt, the + // boundary snapshot (exactly the drained user prompt), and the assembly. + expect(seen).toHaveLength(1) + expect(seen[0]!.boundaryRoles).toEqual(['user']) + expect(typeof seen[0]!.system).toBe('string') + }) + + it('with no contributions the header omits both fields and the request is the bare derivation', async () => { + const adapter = new MockAdapter([textResponse('ok')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + // A listener that delegates without contributing — the canonical no-op. + ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next) => next()) + + send(agent, 'hi') + await waitForIdle(ctx, agent) + + const headerEvent = events(agent).find(e => e.type === 'request/header') + expect(headerEvent?.type === 'request/header' && 'messagePrefix' in headerEvent.data.header).toBe(false) + expect(headerEvent?.type === 'request/header' && 'messageSuffix' in headerEvent.data.header).toBe(false) + expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) + }) + + it('the frozen seed rejects in-place mutation — a contribution is a returned extension', async () => { + const adapter = new MockAdapter([textResponse('ok')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + let mutationError: unknown + ctx.on('agent/request-messages', async (_agent, _turn, _step, messages, _context, next): Promise => { + try { + messages.before.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) + } catch (error: unknown) { + mutationError = error + } + return next() + }) + + send(agent, 'hi') + await waitForIdle(ctx, agent) + + expect(mutationError).toBeInstanceOf(TypeError) + expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) + }) + + it('a per-step contribution change is logged as a header delta, so every request stays reconstructable', async () => { + const adapter = new MockAdapter([ + toolCallResponse('c1', 'echo', { text: 'ping' }), + textResponse('done'), + ]) + const ctx = await harness(adapter) + ctx.tools.register(defineTool({ + name: 'echo', description: 'echo', parameters: { text: { type: 'string' } }, + async execute(args) { return [{ type: 'text', text: String(args.text) }] }, + })) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + let step = 0 + ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next): Promise => { + const result = await next() + step += 1 + return { before: [...result.before, { role: 'user', content: [{ type: 'text', text: `reminder v${step}` }] }], after: result.after } + }) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + expect(adapter.requests[0]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'reminder v1' }] }) + expect(adapter.requests[1]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'reminder v2' }] }) + // Step 2's changed prefix rides a request/header-delta whose fold matches + // what the second request actually sent. + const delta = events(agent).find(e => e.type === 'request/header-delta') + expect(delta?.type === 'request/header-delta' && delta.data.messagePrefix).toEqual([{ role: 'user', content: [{ type: 'text', text: 'reminder v2' }] }]) + expect(foldRequestHeader(agent.session.events)?.messagePrefix).toEqual([{ role: 'user', content: [{ type: 'text', text: 'reminder v2' }] }]) + }) +}) + describe('agent/turn-continuation (ContinuationDecision)', () => { it('a continue decision with a reason records next-step steering in the same turn', async () => { const adapter = new MockAdapter([textResponse('step 1 no tools'), textResponse('step 2')]) diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 9e15356ed0..64a5516761 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -45,6 +45,7 @@ Turn and step boundaries are NOT mirrored as `agent/*` emits: a consumer that ne - `agent/prompt-submit` — decide what happens to one drained queued message before it becomes a `user/message`: `PromptDecision` = `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (drop it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`). Maps onto Claude Code's `UserPromptSubmit`. - `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step. - `agent/request` — shape the call config before the model call: a frozen `LlmCallConfig` seed in, a replacement out (model switching, sampling overrides). Content is not shapeable here — every request is a pure function of the session log ([reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)); the loop logs whatever config the request actually uses as a `request/header*` event +- `agent/request-messages` — contribute request-ONLY messages around the derived history: a frozen empty `RequestMessages` seed in, an extension of `await next()` out (`before` messages precede the boundary snapshot in the request, `after` messages follow it). For per-request advisory context the model must see now but that must not become durable history; the loop records the contributions on the request's `request/header*` event (`EpochHeader.messagePrefix`/`messageSuffix`), so `deriveMessages()` stays untouched and the request stays reconstructable. Cost model: contributions ride the request's uncached tail and are re-paid at full price on every request they appear in — put session-frozen content in `before` (cacheable prefix; a mid-session change busts the cache for everything after it), route low-frequency change notices through `agent.inject()` instead (paid once, prefix-cached thereafter), and reserve `after` for small, frequently refreshed state snapshots - `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records) - `agent/turn-continuation` — override the continue/stop decision via `ContinuationDecision` = `{action:'stop'}` or `{action:'continue', reason?}` (a `continue` `reason` is recorded as next-step steering in the same turn — the typed `/goal` pattern). Force-continue `/loop`, force-stop budget guard. diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 1fd6a57867..9d4fa4f10c 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -17,7 +17,8 @@ * consumer that wants the live transcript subscribes here. * - **`agent/*`** (this module) — the LIVE runtime surface. Always carries the * live `Agent`. Two shapes: INTERCEPTION seams (the `agent/prompt-submit`/ - * `agent/request`/`agent/step-result`/`agent/turn-continuation` waterfalls and + * `agent/request`/`agent/request-messages`/`agent/step-result`/ + * `agent/turn-continuation` waterfalls and * the serial `agent/pre-step`) that mutate/veto, and TRANSIENT emits * (`agent/status`, `agent/error`, `agent/created`/ * `agent/disposed`, `agent/queued`, `agent/session-start`) @@ -45,7 +46,7 @@ import type { Branded } from '@deepseek-ai/dsh-brand' import type { ContentBlock, LlmCallConfig, Message, MessageSource } from '@deepseek-ai/dsh-llm' -import type {} from '@deepseek-ai/dsh-system-prompt' +import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt' /** Identifies one live agent in the registry. */ export type AgentId = Branded<'AgentId'> @@ -138,6 +139,49 @@ export type ContinuationDecision = | { action: 'stop' } | { action: 'continue'; reason?: HookContext } +/** + * Request-ONLY messages an `agent/request-messages` waterfall listener + * contributes around the derived history of ONE LLM request: `before` messages + * precede the derived history in `GenerateOptions.messages`, `after` messages + * follow it. They are NOT session events — nothing here enters the session log + * as durable history, `Session.deriveMessages()` never returns them, and the + * next step recomputes them from scratch. The loop records the non-empty + * arrays on the request's `request/header*` event (`EpochHeader.messagePrefix` + * / `messageSuffix`), so the request stays reconstructable from the log (the + * reconstructability RFC). For content that must become durable conversation + * history, use the log channels instead: `agent.inject()`, steering, or + * prompt-submit `additionalContext`. + */ +export interface RequestMessages { + /** Messages placed before the derived history in the request. */ + before: Message[] + /** Messages placed after the derived history in the request. */ + after: Message[] +} + +/** + * Read-only facts about the request an `agent/request-messages` listener is + * contributing to. Everything here is already fixed when the seam fires: the + * step is open, the boundary snapshot is taken, and the system prompt is + * assembled — a listener uses these to DECIDE what to contribute (e.g. render + * a workspace-dependent reminder, or skip one already present in history), + * never to mutate them. + */ +export interface RequestMessagesContext { + /** The rendered system prompt this request will carry. */ + system: string + /** The prompt assembly the system prompt was rendered from (sections + tools). */ + assembly: PromptAssembly + /** + * The boundary snapshot: the derived history this request will carry between + * `before` and `after`. A frozen snapshot — treat it as read-only; content + * for the NEXT request flows through the log channels. + */ + boundaryMessages: readonly Message[] + /** Aborts in-flight listener work when the step is torn down. */ + signal: AbortSignal +} + /** * Why an agent's session lifecycle began, carried by `agent/session-start`. A * bridge keys its SessionStart hook's matcher on this (Claude Code's @@ -351,8 +395,9 @@ declare module 'cordis' { * ALL a listener shapes here: every request is a pure function of the * session log (the reconstructability RFC), so model-visible content * flows through the log channels — `inject()`, steering, prompt-submit - * `additionalContext`, prompt sections via `system-prompt/assemble` — - * never through request mutation, and the loop records whatever config + * `additionalContext`, prompt sections via `system-prompt/assemble`, or + * header-logged request-only messages via {@link agent/request-messages} + * — never through request mutation, and the loop records whatever config * the request actually uses as a `request/header*` event before dispatch. * The step's messages are already snapshotted when this fires (the * `step/start` boundary): an `inject()` from a listener here lands in the @@ -367,6 +412,47 @@ declare module 'cordis' { * @mode waterfall */ 'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise + /** + * Waterfall: contribute request-ONLY messages around the derived history — + * a {@link RequestMessages} whose `before` messages precede the boundary + * snapshot in `GenerateOptions.messages` and whose `after` messages follow + * it. Fires once per step, inside the open step, after the + * {@link agent/request} config waterfall and before the loop logs the + * request header. This is the seam for per-request advisory context the + * model must see NOW but that must NOT become durable history (a skills + * catalog, an environment reminder): contributions are recorded on the + * request's `request/header*` event (`EpochHeader.messagePrefix` / + * `messageSuffix`) — never as session messages — so + * `Session.deriveMessages()` stays untouched and the request remains + * reconstructable from the log. + * + * The seed is frozen and empty; a contributing listener returns a NEW + * {@link RequestMessages} extending `await next()` (spread its arrays — + * never mutate them), so contributions compose across plugins in + * registration order. The boundary snapshot is already taken when this + * fires: a `session.append`/`inject()` from a listener here lands in the + * log but joins the NEXT request — contribute through the returned value, + * not the session. Call `next()` to delegate, or return a + * {@link RequestMessages} without it to short-circuit. + * + * Pick the channel by change frequency (the cost model): a contribution + * rides the request's uncached tail, re-tokenized at full price on EVERY + * request it appears in — cheap only while small. Session-FROZEN content + * belongs in `before`, where it extends the cacheable prefix at zero + * marginal cost (but changing it mid-session invalidates the provider + * cache for the entire history after it). A LOW-FREQUENCY change notice + * belongs in durable history via `agent.inject()` — appended once, + * prefix-cached thereafter. Reserve `after` for small, frequently + * refreshed state snapshots, where a durable chain of stale copies would + * bloat the log and mislead the model. + * @param agent - the agent making the model call. + * @param turn - the open turn number. + * @param step - the step whose request this is. + * @param messages - the frozen empty seed; return an extended replacement to contribute. + * @param context - read-only request facts ({@link RequestMessagesContext}). + * @mode waterfall + */ + 'agent/request-messages'(agent: Agent, turn: number, step: number, messages: RequestMessages, context: RequestMessagesContext, next: () => Promise): Promise /** * Waterfall: post-process the assembled assistant {@link Message} before * tool dispatch (validation, content rewriting, …). diff --git a/packages/core/session/README.md b/packages/core/session/README.md index 0ae5bbf39e..7fa16d0f3d 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -51,7 +51,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`. ### Request-header reconstruction (`request-header.ts`) -The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools ≡ absent fields). +The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config / whole request-only message arrays) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools/messagePrefix/messageSuffix ≡ absent fields; a delta's EMPTY message array encodes the transition back to absence). `EpochHeader.messagePrefix`/`messageSuffix` are the durable record of the `agent/request-messages` waterfall's request-only contributions — the request is `messagePrefix + derived history + messageSuffix`, and `deriveMessages()` never returns them. ### Session event vocabulary (`types.ts`) diff --git a/packages/core/session/src/request-header.ts b/packages/core/session/src/request-header.ts index d83da16197..a891237425 100644 --- a/packages/core/session/src/request-header.ts +++ b/packages/core/session/src/request-header.ts @@ -13,14 +13,24 @@ */ import { callConfigEquals } from '@deepseek-ai/dsh-llm' -import type { LlmCallConfig, ToolSchema } from '@deepseek-ai/dsh-llm' +import type { LlmCallConfig, Message, ToolSchema } from '@deepseek-ai/dsh-llm' import type { EpochHeader, SessionEvent, SystemDelta, ToolsDelta } from './types.ts' +/** The `request/header-delta` payload shape: each present field amends the folded header. */ +type HeaderDelta = { + system?: SystemDelta + tools?: ToolsDelta + config?: LlmCallConfig + messagePrefix?: Message[] + messageSuffix?: Message[] +} + /** - * Normalize a header to canonical form: an empty system prompt and an empty - * tool list become ABSENT fields, matching how requests are built (both - * request-build spreads skip empty values). Diff, fold, and comparison all - * operate on canonical headers, so "no system prompt" has exactly one + * Normalize a header to canonical form: an empty system prompt, an empty + * tool list, and empty request-only message arrays become ABSENT fields, + * matching how requests are built (the request-build spreads skip empty + * values). Diff, fold, and comparison all operate on canonical headers, so + * "no system prompt" (and "no request-only messages") has exactly one * representation. * @param header - the header to normalize (not mutated). * @returns the canonical header. @@ -30,6 +40,8 @@ export function canonicalHeader(header: EpochHeader): EpochHeader { config: header.config, ...header.system !== undefined && header.system.length > 0 ? { system: header.system } : {}, ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {}, + ...header.messagePrefix !== undefined && header.messagePrefix.length > 0 ? { messagePrefix: header.messagePrefix } : {}, + ...header.messageSuffix !== undefined && header.messageSuffix.length > 0 ? { messageSuffix: header.messageSuffix } : {}, } } @@ -109,37 +121,47 @@ function applyTools(prev: readonly ToolSchema[], delta: ToolsDelta): ToolSchema[ * writer's round-trip guard runs (`applyHeaderDelta(prev, delta)` must equal * the intended header) and the loop runs to skip logging an unchanged header. * Tools compare per-schema IN ORDER (canonical JSON), so a pure reordering is - * correctly unequal. + * correctly unequal; request-only message arrays compare as canonical JSON + * (both sides come from the same build path, so key order matches when the + * values do). * @param a - one canonical header. * @param b - the other. - * @returns whether config, system, and tools (in order) all match. + * @returns whether config, system, tools (in order), and request-only messages all match. */ export function headerEquals(a: EpochHeader, b: EpochHeader): boolean { if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false + if (!sameMessages(a.messagePrefix, b.messagePrefix) || !sameMessages(a.messageSuffix, b.messageSuffix)) return false const at = a.tools ?? [] const bt = b.tools ?? [] return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema)) } +/** Canonical JSON equality over request-only message arrays; absence equals the empty array. */ +function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean { + return JSON.stringify(a ?? []) === JSON.stringify(b ?? []) +} + /** * Compute the `request/header-delta` payload between two canonical headers, * or undefined when they are equal. The caller MUST round-trip the result * ({@link applyHeaderDelta} on `prev` deep-equals `next`) before logging it — * the encoding cannot express every change (a pure tool reordering) — and * fall back to a full `request/header` snapshot when the check fails. + * Request-only messages are replaced whole (small advisory content, not worth + * diffing); an empty replacement array encodes the transition to "none". * @param prev - the folded header the log currently implies. * @param next - the header the next request will actually use. * @returns the delta payload, or undefined when nothing changed. */ -export function diffHeader( - prev: EpochHeader, next: EpochHeader, -): { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } | undefined { - const delta: { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } = {} +export function diffHeader(prev: EpochHeader, next: EpochHeader): HeaderDelta | undefined { + const delta: HeaderDelta = {} if (prev.system !== next.system) delta.system = diffSystem(prev.system, next.system) const prevTools = prev.tools ?? [] const nextTools = next.tools ?? [] if (JSON.stringify(prevTools) !== JSON.stringify(nextTools)) delta.tools = diffTools(prevTools, nextTools) if (!callConfigEquals(prev.config, next.config)) delta.config = next.config + if (!sameMessages(prev.messagePrefix, next.messagePrefix)) delta.messagePrefix = next.messagePrefix ?? [] + if (!sameMessages(prev.messageSuffix, next.messageSuffix)) delta.messageSuffix = next.messageSuffix ?? [] return Object.keys(delta).length > 0 ? delta : undefined } @@ -151,15 +173,17 @@ export function diffHeader( * @param delta - the logged delta payload. * @returns the canonical header after the delta. */ -export function applyHeaderDelta( - prev: EpochHeader, delta: { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }, -): EpochHeader { +export function applyHeaderDelta(prev: EpochHeader, delta: HeaderDelta): EpochHeader { const system = delta.system !== undefined ? applySystem(prev.system, delta.system) : prev.system const tools = delta.tools !== undefined ? applyTools(prev.tools ?? [], delta.tools) : prev.tools + const messagePrefix = delta.messagePrefix ?? prev.messagePrefix + const messageSuffix = delta.messageSuffix ?? prev.messageSuffix return canonicalHeader({ config: delta.config ?? prev.config, ...system !== undefined ? { system } : {}, ...tools !== undefined ? { tools } : {}, + ...messagePrefix !== undefined ? { messagePrefix } : {}, + ...messageSuffix !== undefined ? { messageSuffix } : {}, }) } diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index ec227e9884..32a10c7bca 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -1,5 +1,5 @@ import type { Branded } from '@deepseek-ai/dsh-brand' -import type { CallId, ContentBlock, LlmCallConfig, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm' +import type { CallId, ContentBlock, LlmCallConfig, Message, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm' /** Identifies one session in the store (and its persistence artifacts). */ export type SessionId = Branded<'SessionId'> @@ -177,14 +177,16 @@ export interface TodoItem { } /** - * The request header: everything about an LLM request besides its message - * content — the call configuration plus the rendered system prompt and tool - * schemas. Logged session state (the reconstructability RFC): a + * The request header: everything about an LLM request besides its derived + * message history — the call configuration plus the rendered system prompt, + * tool schemas, and any request-only messages. Logged session state (the + * reconstructability RFC): a * {@link SessionEventMap} `request/header` snapshot installs one, a * `request/header-delta` amends it, and folding those events over the log * (`foldRequestHeader`) reconstructs the header any request was built under. - * Canonical form: an empty system prompt and an empty tool list are ABSENT - * fields, matching how requests are built. + * Canonical form: an empty system prompt, an empty tool list, and empty + * request-only message arrays are ABSENT fields, matching how requests are + * built. */ export interface EpochHeader { /** The conversation's call configuration (model + sampling scalars). */ @@ -193,6 +195,15 @@ export interface EpochHeader { system?: string /** Assembled tool schemas; absent for a tool-less request. */ tools?: ToolSchema[] + /** + * Request-only messages sent BEFORE the derived history (the + * `agent/request-messages` waterfall's `before` contributions). Not session + * history — `deriveMessages()` never returns them — so the header is their + * only durable record; absent when the request carried none. + */ + messagePrefix?: Message[] + /** Request-only messages sent AFTER the derived history; absent when none. */ + messageSuffix?: Message[] } /** @@ -350,15 +361,19 @@ export interface SessionEventMap { 'request/header': { header: EpochHeader; reason: RequestHeaderReason } /** * Amendment to the folded {@link EpochHeader}: at least one of a - * {@link SystemDelta}, a {@link ToolsDelta}, or a whole replacement - * {@link LlmCallConfig} (four scalars — not worth diffing). Appended by the + * {@link SystemDelta}, a {@link ToolsDelta}, a whole replacement + * {@link LlmCallConfig} (four scalars — not worth diffing), or a whole + * replacement request-only message array (`messagePrefix`/`messageSuffix` — + * small advisory content, replaced whole; an EMPTY array encodes the + * transition to "none", mirroring the canonical form's absent field). + * Appended by the * loop inside the step, before dispatch, when the header for this request * differs from the fold of the log so far; the writer verifies * `applyHeaderDelta(previous, delta)` reproduces the new header exactly and * falls back to a `'fallback'` `request/header` snapshot when it cannot, so * a logged delta ALWAYS round-trips. NOT a {@link SurfaceEventType}. */ - 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } + 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[]; messageSuffix?: Message[] } } export type SessionEventType = keyof SessionEventMap diff --git a/packages/core/session/tests/request-header.spec.ts b/packages/core/session/tests/request-header.spec.ts index c2368c46fe..9db46598ac 100644 --- a/packages/core/session/tests/request-header.spec.ts +++ b/packages/core/session/tests/request-header.spec.ts @@ -8,9 +8,9 @@ */ import { describe, expect, it } from 'vitest' -import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader } from '@deepseek-ai/dsh-session' +import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session' import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session' -import type { ToolSchema } from '@deepseek-ai/dsh-llm' +import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm' const CONFIG = { model: 'm' } @@ -18,6 +18,10 @@ function tool(name: string, description = 'd'): ToolSchema { return { name, description, parameters: { type: 'object' } } } +function msg(text: string): Message { + return { role: 'user', content: [{ type: 'text', text }] } +} + /** Round-trip helper: diff must reproduce `next` from `prev` exactly. */ function roundTrip(prev: EpochHeader, next: EpochHeader): ReturnType { const delta = diffHeader(prev, next) @@ -103,6 +107,49 @@ describe('diffHeader / applyHeaderDelta', () => { }) }) +describe('request-only messages (messagePrefix / messageSuffix)', () => { + it('canonicalHeader normalizes empty arrays to absent fields', () => { + expect(canonicalHeader({ config: CONFIG, messagePrefix: [], messageSuffix: [] })).toEqual({ config: CONFIG }) + const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')], messageSuffix: [msg('s')] }) + expect(full.messagePrefix).toEqual([msg('p')]) + expect(full.messageSuffix).toEqual([msg('s')]) + }) + + it('headerEquals treats absence and empty as one representation, content differences as unequal', () => { + expect(headerEquals(canonicalHeader({ config: CONFIG }), { config: CONFIG, messagePrefix: [] })).toBe(true) + expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG, messagePrefix: [msg('b')] })).toBe(false) + expect(headerEquals({ config: CONFIG, messageSuffix: [msg('a')] }, { config: CONFIG })).toBe(false) + }) + + it('replaces a changed prefix whole and leaves an untouched suffix alone', () => { + const prev = canonicalHeader({ config: CONFIG, messagePrefix: [msg('old')], messageSuffix: [msg('keep')] }) + const next = canonicalHeader({ config: CONFIG, messagePrefix: [msg('new'), msg('more')], messageSuffix: [msg('keep')] }) + const delta = roundTrip(prev, next) + expect(delta).toEqual({ messagePrefix: [msg('new'), msg('more')] }) + }) + + it('round-trips framing gained from a bare header and lost back to one (empty array encodes absence)', () => { + const none = canonicalHeader({ config: CONFIG }) + const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')], messageSuffix: [msg('s')] }) + const gained = roundTrip(none, some) + expect(gained).toEqual({ messagePrefix: [msg('p')], messageSuffix: [msg('s')] }) + const lost = roundTrip(some, none) + expect(lost).toEqual({ messagePrefix: [], messageSuffix: [] }) + }) + + it('folds framing deltas over the log like any other header amendment', () => { + const session = new Session(SessionId('fold-framing')) + session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + const first = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v1')] }) + session.append('request/header', { header: first, reason: 'initial' }) + const second = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v2')] }) + session.append('request/header-delta', diffHeader(first, second)!) + expect(foldRequestHeader(session.events)).toEqual(second) + session.append('request/header-delta', diffHeader(second, canonicalHeader({ config: CONFIG }))!) + expect(foldRequestHeader(session.events)).toEqual({ config: CONFIG }) + }) +}) + describe('foldRequestHeader', () => { function headerEvents(session: Session): readonly SessionEvent[] { return session.events diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts index 7163ddc1d9..f6212e7870 100644 --- a/packages/llm/llm/src/types.ts +++ b/packages/llm/llm/src/types.ts @@ -168,6 +168,12 @@ export interface ToolSchema { /** A single model request, fully assembled. */ export interface GenerateOptions { model: string + /** + * Ordered conversation messages, exactly as the provider sees them (after + * the `system` slot). A loop-built request assembles them as + * `EpochHeader.messagePrefix` + the derived history + `messageSuffix` + * (dsh-agent-loop); a hand-built one-shot passes any list. + */ messages: Message[] /** System prompt text (adapters map to the provider's system slot). */ system?: string diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts index f35fbafa1d..024838ea4c 100644 --- a/packages/support/invariants/src/index.ts +++ b/packages/support/invariants/src/index.ts @@ -367,8 +367,11 @@ export function apply(ctx: Context, config: Config = {}): void { // hand-built one-shot (compaction summarize) is unfrozen and skipped — must // be EXACTLY what the session log reconstructs: // - // - messages: the derivation over the log prefix strictly before the - // in-flight step's `step/start` (the reconstruction boundary). Compared + // - messages: the folded header's request-only messages (messagePrefix / + // messageSuffix — the `agent/request-messages` contributions, logged on + // the header because no session event carries them) framing the + // derivation over the log prefix strictly before the in-flight step's + // `step/start` (the reconstruction boundary). The derivation is compared // against a FRESH Session built over that prefix — the same projection // code with zero shared state, so the live cache under test cannot vouch // for itself. Boundary-correct by construction: content appended after @@ -408,18 +411,22 @@ export function apply(ctx: Context, config: Config = {}): void { if (boundary === -1) { throw new InvariantError('a loop-built request with no step/start in its session log') } - const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary))) - // JSON equality is sound here: both sides are structuredClones produced by - // the same projection code path, so key insertion order matches when the - // values do. - if (JSON.stringify(options.messages) !== JSON.stringify(rebuilt.deriveMessages())) { - throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`) - } - const header = foldRequestHeader(events) if (header === undefined) { throw new InvariantError('a loop-built request with no request/header event in its session log') } + const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary))) + // The reconstruction equation: the folded header's request-only messages + // frame the boundary derivation (prefix + derived + suffix) — the loop + // logs the header event BEFORE dispatch, so the fold already covers this + // request's contributions. JSON equality is sound here: both sides are + // structuredClones produced by the same projection/build code path, so key + // insertion order matches when the values do. + const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages(), ...header.messageSuffix ?? []] + if (JSON.stringify(options.messages) !== JSON.stringify(expected)) { + throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`) + } + const headerMatches = options.model === header.config.model && options.system === header.system && options.temperature === header.config.temperature diff --git a/packages/support/invariants/tests/invariants.spec.ts b/packages/support/invariants/tests/invariants.spec.ts index 489cfb9817..cccd6a54d4 100644 --- a/packages/support/invariants/tests/invariants.spec.ts +++ b/packages/support/invariants/tests/invariants.spec.ts @@ -707,6 +707,22 @@ describe('request-reconstruction cross-check (llm/stream)', () => { expect(() => { dispatch(ctx, options) }).not.toThrow() }) + it('expects the folded header\'s request-only messages to frame the derivation (prefix + derived + suffix)', async () => { + const { ctx, session, boundary } = await requestSetup() + const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: 'catalog' }] } + const suffix = { role: 'user' as const, content: [{ type: 'text' as const, text: 'trailing note' }] } + session.append('request/header-delta', { messagePrefix: [prefix], messageSuffix: [suffix] }) + // The framed request matches the fold… + const framed = Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary, suffix]), sessionId: session.id }) + expect(() => { dispatch(ctx, framed) }).not.toThrow() + // …a request that DROPPED the logged framing diverges… + const bare = Object.freeze({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id }) + expect(() => { dispatch(ctx, bare) }).toThrow(/diverges from the boundary derivation/) + // …and so does one that misplaced it (suffix sent as a prefix). + const misplaced = Object.freeze({ model: 'm', messages: Object.freeze([suffix, prefix, ...boundary]), sessionId: session.id }) + expect(() => { dispatch(ctx, misplaced) }).toThrow(/diverges from the boundary derivation/) + }) + it('rejects a frozen request whose messages diverge from the boundary derivation', async () => { const { ctx, session, boundary } = await requestSetup() const messages = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }] diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index b5c648527e..7291bee4ca 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -15,6 +15,8 @@ { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" }, + { "doc": "docs/core-data-structures/core.md", "symbol": "RequestMessages", "source": "packages/core/agent/src/types.ts" }, + { "doc": "docs/core-data-structures/core.md", "symbol": "RequestMessagesContext", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" }, { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" }, From f3d26ed04912aef6a65f40fe48f4bc790ea558fa Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 7 Jul 2026 20:55:13 +0800 Subject: [PATCH 030/119] fix request-messages boundary immutability --- packages/core/agent-loop/src/loop.ts | 3 ++- .../agent-loop/tests/interception.spec.ts | 23 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index 600bb211a1..0ca7a06645 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -727,9 +727,10 @@ async function runStep( // so a listener's session append lands past the boundary and joins the NEXT // request — the same window rule as the `agent/request` waterfall. const emptyRequestMessages: RequestMessages = deepFreeze({ before: [], after: [] }) + const requestMessagesBoundary = deepFreeze([...boundaryMessages]) const requestMessages = await ctx.waterfall( 'agent/request-messages', agent, turn, step, emptyRequestMessages, - { system, assembly, boundaryMessages, signal }, + { system, assembly, boundaryMessages: requestMessagesBoundary, signal }, () => Promise.resolve(emptyRequestMessages), ) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index 36b9100b85..14db911a7e 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -418,6 +418,29 @@ describe('agent/request-messages (RequestMessages)', () => { expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) }) + it('the read-only boundary context rejects in-place mutation before the request is built', async () => { + const adapter = new MockAdapter([textResponse('ok')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + let mutationError: unknown + ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, context, next): Promise => { + try { + const mutableBoundary = context.boundaryMessages as Message[] + mutableBoundary.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) + } catch (error: unknown) { + mutationError = error + } + return next() + }) + + send(agent, 'hi') + await waitForIdle(ctx, agent) + + expect(mutationError).toBeInstanceOf(TypeError) + expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) + }) + it('a per-step contribution change is logged as a header delta, so every request stays reconstructable', async () => { const adapter = new MockAdapter([ toolCallResponse('c1', 'echo', { text: 'ping' }), From 1f5db6e0b0ce3b7ee055a6712167ee474910b1e7 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 7 Jul 2026 22:39:05 +0800 Subject: [PATCH 031/119] docs: satisfy the export-JSDoc gate across the workflow packages Master's verify-export-jsdoc landed mid-stack; complete the six missing @param/@returns on the workflow trio's public surface (and the services catalog they regenerate into). --- docs/cordis-catalog/services.md | 2 +- packages/workflow/workflow-vm/src/runtime.ts | 4 ++++ packages/workflow/workflow/src/index.ts | 6 +++++- packages/workflow/workflow/src/types.ts | 6 +++++- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index f292045c69..3e991726d4 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -243,7 +243,7 @@ Semantics every implementation must honor: abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Source: [`packages/workflow/workflow/src/index.ts:198`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:202`](../../packages/workflow/workflow/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index f1901ffaf7..0938b7f2c9 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -225,6 +225,8 @@ export class WorkflowExecution { * `disposeGraceMs` (parked on a promise no hook owns) is abandoned so * `result` settles regardless (see {@link abandoned}). Idempotent; the * first reason wins. + * @param reason - human-readable cause, carried on the CANCELLED error and + * into child `run.cancel()` calls (default `'workflow cancelled'`). */ cancel(reason?: string): void { if (this.cancelReason !== undefined) return @@ -244,6 +246,8 @@ export class WorkflowExecution { * cancellation (or outlived its post-cancel grace and was abandoned — see * {@link abandoned}). After settlement, any stray children a script fired * without awaiting are aborted (their `agent()` wrappers dispose them). + * @returns the settled outcome — this promise NEVER rejects (the seam's + * `result`-never-rejects contract); every failure maps to a variant. */ async drive(): Promise { try { diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 31b9eed038..288f6af952 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -168,7 +168,11 @@ export class WorkflowError extends HarnessError { } } -/** Whether combinators must re-throw `error` instead of mapping the item to `null`. */ +/** + * Whether combinators must re-throw `error` instead of mapping the item to `null`. + * @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm). + * @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set. + */ export function isFatalWorkflowError(error: unknown): boolean { return error instanceof WorkflowError && error.fatal } diff --git a/packages/workflow/workflow/src/types.ts b/packages/workflow/workflow/src/types.ts index 01e5d08bf0..767fb8257b 100644 --- a/packages/workflow/workflow/src/types.ts +++ b/packages/workflow/workflow/src/types.ts @@ -12,7 +12,11 @@ import type { Agent, AgentId } from '@deepseek-ai/dsh-agent' /** Identifies one workflow run. */ export type WorkflowRunId = Branded<'WorkflowRunId'> -/** Brand a string as a {@link WorkflowRunId}. */ +/** + * Brand a string as a {@link WorkflowRunId}. + * @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures). + * @returns the same string, branded. + */ export function WorkflowRunId(id: string): WorkflowRunId { return id as WorkflowRunId } From 737e1f7c0ac824bbd9aa61f6d856497767a4e36c Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 7 Jul 2026 23:22:05 +0800 Subject: [PATCH 032/119] chore: absorb master's explicit tool order into the stack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tool-order feature canonicalizes the model-facing list (alphabetical absent a configured toolOrder), so the header-pinning text-turn fixture is re-recorded on the stacked tree — every other fixture stores the header as scrubbed tokens and needed nothing. AGENTS.md condensed back under its ceiling after the merge union. --- AGENTS.md | 4 +- .../tests/snapshots/text-turn/session.jsonl | 69 +++++++++---------- .../snapshots/text-turn/stdout.golden.jsonl | 9 +-- 3 files changed, 38 insertions(+), 44 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5f2f8e4cdd..fc33e2f049 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ # AGENTS.md -This is the monorepo of the DeepSeek Harness group; it hosts **DeepSeek Harness SDK**, a plugin-based SDK for building agent harnesses. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; the documentation standard is [docs/AGENTS.md](docs/AGENTS.md). +The DeepSeek Harness group monorepo, hosting **DeepSeek Harness SDK** — a plugin-based SDK for building agent harnesses on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; the documentation standard is [docs/AGENTS.md](docs/AGENTS.md). ## Pre-release stance: foundation over blast radius -**This applies only while the harness is unreleased — remove this section at the first tagged release.** There are no external consumers, so optimize for the correct foundation, not a small diff: move files, rename public symbols, repackage plugins, and update every reference in the same change. No backward-compat shims, deprecation aliases, or re-export stubs. On-disk formats need no migrations — a backend REJECTS anything not at the current version. Two sanctioned version stances: monotonic bump-and-reject (the SQLite backend's `SCHEMA_VERSION`), and a pinned `0` that absorbs all shape churn (`SESSION_FORMAT_VERSION` in `dsh-session`, documented "no compatibility implied"). Real version policy begins at the first release. +**Applies only while the harness is unreleased — remove this section at the first tagged release.** With no external consumers, optimize for the correct foundation, not a small diff: move files, rename public symbols, repackage plugins, and update every reference in the same change. No backward-compat shims, deprecation aliases, or re-export stubs. On-disk formats need no migrations — a backend REJECTS anything not at the current version. Two sanctioned version stances: monotonic bump-and-reject (the SQLite backend's `SCHEMA_VERSION`), and a pinned `0` that absorbs all shape churn (`SESSION_FORMAT_VERSION` in `dsh-session`, documented "no compatibility implied"). Real version policy begins at the first release. ## Repository layout diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index 008d968c01..3e91a5a62a 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -1,36 +1,33 @@ -{"type":"session","version":0,"id":"72de3ed9-a2cb-44da-a9fd-5249b5c65b52","createdAt":1783352040349,"cwd":"/tmp/acp-snap-cwd-7wwwVQ"} -{"type":"turn/start","seq":0,"time":1783352040353,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783352040354,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783352040355,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783352040356,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-7wwwVQ.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)."},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783352041017,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783352041018,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783352041114,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783352041142,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783352041142,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783352041142,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783352041142,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":11,"time":1783352041143,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":12,"time":1783352041143,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":13,"time":1783352041173,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":14,"time":1783352041173,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} -{"type":"assistant/chunk","seq":15,"time":1783352041174,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":16,"time":1783352041174,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"P"}}} -{"type":"assistant/chunk","seq":17,"time":1783352041174,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONG"}}} -{"type":"assistant/chunk","seq":18,"time":1783352041174,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} -{"type":"assistant/chunk","seq":19,"time":1783352041201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":20,"time":1783352041201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" not"}}} -{"type":"assistant/chunk","seq":21,"time":1783352041201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}} -{"type":"assistant/chunk","seq":22,"time":1783352041201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" any"}}} -{"type":"assistant/chunk","seq":23,"time":1783352041202,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} -{"type":"assistant/chunk","seq":24,"time":1783352041202,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":25,"time":1783352041227,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":26,"time":1783352041228,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"P"}}} -{"type":"assistant/chunk","seq":27,"time":1783352041228,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONG"}}} -{"type":"assistant/chunk","seq":28,"time":1783352041228,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."}}}} -{"type":"assistant/chunk","seq":29,"time":1783352041228,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PONG"}}}} -{"type":"assistant/chunk","seq":30,"time":1783352041228,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2868,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}}}} -{"type":"assistant/chunk","seq":31,"time":1783352041228,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":32,"time":1783352041230,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."},{"type":"text","text":"PONG"}],"usage":{"inputTokens":2868,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"surfaceOp":"append"} -{"type":"step/end","seq":33,"time":1783352041231,"data":{"turn":1,"step":1}} -{"type":"turn/end","seq":34,"time":1783352041231,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"423e2c78-075e-4286-8027-85b0e64da45d","createdAt":1783437535685,"cwd":"/tmp/acp-snap-cwd-XUOYdd"} +{"type":"turn/start","seq":0,"time":1783437535688,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783437535689,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783437535690,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783437535690,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XUOYdd.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)."},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783437536390,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783437536390,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783437536568,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783437536591,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":11,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":12,"time":1783437536615,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":13,"time":1783437536616,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":14,"time":1783437536647,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"P"}}} +{"type":"assistant/chunk","seq":15,"time":1783437536648,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONG"}}} +{"type":"assistant/chunk","seq":16,"time":1783437536648,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\""}}} +{"type":"assistant/chunk","seq":17,"time":1783437536674,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":18,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" no"}}} +{"type":"assistant/chunk","seq":19,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} +{"type":"assistant/chunk","seq":20,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":21,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":22,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"P"}}} +{"type":"assistant/chunk","seq":23,"time":1783437536702,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONG"}}} +{"type":"assistant/chunk","seq":24,"time":1783437536703,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"."}}} +{"type":"assistant/chunk","seq":25,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"PONG.\" and no tools."}}}} +{"type":"assistant/chunk","seq":26,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PONG."}}}} +{"type":"assistant/chunk","seq":27,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2867,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":16}}}} +{"type":"assistant/chunk","seq":28,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":29,"time":1783437536706,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"PONG.\" and no tools."},{"type":"text","text":"PONG."}],"usage":{"inputTokens":2867,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":16}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28],"surfaceOp":"append"} +{"type":"step/end","seq":30,"time":1783437536706,"data":{"turn":1,"step":1}} +{"type":"turn/end","seq":31,"time":1783437536706,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl index dda3afb9c5..bc3582f027 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl @@ -8,18 +8,15 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"P"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONG"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\""}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" not"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" use"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" any"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" no"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"P"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONG"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} From 773ecf03f578d1cf8c775fb3d51f6b872cf3ae81 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 00:51:19 +0800 Subject: [PATCH 033/119] workflow: drop the determinism bans (unimplemented-resume pre-support) The Date.now()/Math.random()/argless-new-Date() bans existed solely to keep scripts resume-compatible for the deferred journaling/resume feature. Pre-support for an unimplemented feature is speculative cost: scripts may now read the clock freely; implementing resume reintroduces the bans as a script-contract tightening. The RFC's shipped-state description is updated in place, the tool DESCRIPTION drops the constraint sentence (the pinned text-turn header follows), and the engine README's trust-premise paragraph now leans on absent globals alone. --- .../feature/2026-07-05-dynamic-workflows.md | 4 ++-- docs/tool-catalog.md | 2 +- .../tests/snapshots/text-turn/session.jsonl | 2 +- packages/workflow/tool-workflow/README.md | 2 +- packages/workflow/tool-workflow/src/index.ts | 6 +++--- packages/workflow/workflow-vm/README.md | 4 ++-- packages/workflow/workflow-vm/src/runtime.ts | 20 ------------------- .../workflow-vm/tests/workflow-vm.spec.ts | 11 +--------- 8 files changed, 11 insertions(+), 40 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index daf041a1d8..f7749efa56 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -12,7 +12,7 @@ A workflow capability family at `packages/workflow/` in the bash seam shape (int ### The script contract (Claude Code-compatible) -A script is `export const meta = {...}` (a PURE object literal: `name`, `description`, optional `whenToUse`/`phases`) followed by a plain-JS body with top-level `await`, ending in `return `. The body sees exactly: `agent(prompt, {label, phase, schema, model})`, `parallel(thunks)`, `pipeline(items, ...stages)` (NO cross-stage barrier; `(prev, item, index)` callbacks), `phase(title)`, `log(message)`, and `args`. CC semantics are preserved where they matter to script authors: a failed child resolves `null` (scripts `.filter(Boolean)`); an ordinary stage throw nulls the ITEM and skips its remaining stages; `Date.now()`/`Math.random()`/argless `new Date()` throw (kept banned so future resume support cannot break script compatibility). +A script is `export const meta = {...}` (a PURE object literal: `name`, `description`, optional `whenToUse`/`phases`) followed by a plain-JS body with top-level `await`, ending in `return `. The body sees exactly: `agent(prompt, {label, phase, schema, model})`, `parallel(thunks)`, `pipeline(items, ...stages)` (NO cross-stage barrier; `(prev, item, index)` callbacks), `phase(title)`, `log(message)`, and `args`. CC semantics are preserved where they matter to script authors: a failed child resolves `null` (scripts `.filter(Boolean)`); an ordinary stage throw nulls the ITEM and skips its remaining stages. CC's determinism bans (`Date.now()`/`Math.random()`/argless `new Date()` throwing) are NOT enforced — they exist for CC's journaling/resume, which this cut defers — so a CC-authored script runs unchanged while scripts written here may freely read the clock. One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferred options (`effort`/`isolation`/`agentType`), malformed arguments, schemas outside the supported subset, tripped caps, seam start failures — throws a `WorkflowError` with `fatal: true`, and the combinators RE-THROW fatal errors instead of nulling the item. Without this, a typo'd option dissolves into a `null` indistinguishable from a child failure — the accepted-then-ignored failure mode this repo bans. One addition: the tool's `args` parameter is a JSON OBJECT (a bare list is wrapped as a field) so the wire schema stays honest. @@ -41,7 +41,7 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai ## Deferred (documented non-goals of this cut) - **Background collection** (start tool → run id → completion notice → collect), designed alongside bash/subagent background unification. -- **Journaling + resume** (`resumeFromRunId`, cached agent() prefixes) — the determinism bans already keep scripts resume-compatible. +- **Journaling + resume** (`resumeFromRunId`, cached agent() prefixes) — implementing it reintroduces CC's determinism bans as a script-contract tightening (scripts may read the clock today). - **Saved/bundled workflows** (a `.deepseek/workflows/` registry, slash-command surface) and **script persistence to a run directory** (the tool-call event already records the script durably). - **Nested `workflow()`**, **token `budget`**, and the `effort`/`isolation`/`agentType` agent options (each rejects loud with a message naming it deferred). - **An overall run wall-clock timeout** — cancellation always frees the caller (result settles within the grace), so a cap on total run time is a policy knob for the background redesign, not a correctness need here. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 87b1a8a999..3794b1d7a7 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -293,7 +293,7 @@ Script-body hooks: Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. -Constraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. +Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. ```json { diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index 3e91a5a62a..39898c5003 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783437535688,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783437535689,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783437535690,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783437535690,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XUOYdd.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; `Date.now()`, `Math.random()`, and argless `new Date()` throw (pass timestamps via `args`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)."},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783437535690,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XUOYdd.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)."},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783437536390,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783437536390,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783437536568,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md index 37c9f9f426..44160d8fc1 100644 --- a/packages/workflow/tool-workflow/README.md +++ b/packages/workflow/tool-workflow/README.md @@ -4,7 +4,7 @@ The model-facing **`workflow` tool**: run a JavaScript orchestration script that ## What the model sees -Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, determinism bans, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). The plugin also contributes a `tool:` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona. +Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). The plugin also contributes a `tool:` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona. ## Lifecycle diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts index 4df4d6aba1..a5eae80aec 100644 --- a/packages/workflow/tool-workflow/src/index.ts +++ b/packages/workflow/tool-workflow/src/index.ts @@ -51,8 +51,8 @@ export const Config: z = z.object({ /** * The script-authoring contract, embedded in the tool description. This IS the - * model-facing spec: the meta block, the hooks and their exact semantics, the - * determinism bans, and the supported schema subset. + * model-facing spec: the meta block, the hooks and their exact semantics, and + * the supported schema subset. */ const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. @@ -66,7 +66,7 @@ Script-body hooks: Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`. -Constraints: concurrency and total-agent caps apply; \`Date.now()\`, \`Math.random()\`, and argless \`new Date()\` throw (pass timestamps via \`args\`); no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.` +Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.` type WorkflowCallArgs = { script: string; args?: Record } diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index e81e74dc7e..e29073c2b3 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -4,13 +4,13 @@ The first [`WorkflowService`](../workflow/README.md) implementation: an in-proce ## Trust premise -Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. vm is NOT a security boundary and no attempt is made to contain adversarial values: property reads on script values may run script code (a getter, a `toString`, a proxy trap) on the host stack, and a script determined to hang the process can simply spin past its first await (see the limitations below). Concretely, the context is **escapable by construction**: `node:vm` shares object machinery with the host, so a script can reach the host `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin — the absent globals and determinism bans are API surface that keeps honest scripts portable and resume-compatible, not walls. What the engine DOES guarantee, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection (the app boot layer exits the process on those), values that JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing is an engine swap behind the seam (worker-thread/isolated-vm, where the boundary is serialization by construction), not incremental host-side defenses here. +Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. vm is NOT a security boundary and no attempt is made to contain adversarial values: property reads on script values may run script code (a getter, a `toString`, a proxy trap) on the host stack, and a script determined to hang the process can simply spin past its first await (see the limitations below). Concretely, the context is **escapable by construction**: `node:vm` shares object machinery with the host, so a script can reach the host `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin — the absent globals are API surface that keeps honest scripts portable, not walls. What the engine DOES guarantee, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection (the app boot layer exits the process on those), values that JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing is an engine swap behind the seam (worker-thread/isolated-vm, where the boundary is serialization by construction), not incremental host-side defenses here. ## The script contract it executes - **Meta extraction** (`extractMeta`): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. - **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline). -- **Determinism bans**: `Date.now()`, `Math.random()`, and argless `new Date()` throw (kept even though resume is deferred, so scripts stay resume-compatible); no timers, filesystem, or Node APIs are injected into the context (absence is API surface, not containment — see the trust premise). +- **No ambient APIs**: no timers, filesystem, or Node APIs are injected into the context (absence is API surface, not containment — see the trust premise). ## The value boundary diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index 0938b7f2c9..c4e5d1c651 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -75,25 +75,6 @@ const SUPPORTED_AGENT_OPTIONS = new Set(['label', 'phase', 'schema', 'model']) /** Deferred Claude Code options we name explicitly in the rejection message. */ const DEFERRED_AGENT_OPTIONS = new Set(['effort', 'isolation', 'agentType']) -/** The in-context prelude that bans the nondeterminism sources (kept even though resume is deferred, so scripts stay resume-compatible). */ -const DETERMINISM_PRELUDE = ` -{ - const banned = (name) => () => { - throw new Error(name + ' is not available in workflow scripts (runs must stay deterministic for future resume support; pass timestamps in via args)') - } - Math.random = banned('Math.random()') - Date.now = banned('Date.now()') - const RealDate = Date - globalThis.Date = new Proxy(RealDate, { - construct(target, args, newTarget) { - if (args.length === 0) banned('argless new Date()')() - return Reflect.construct(target, args, newTarget) - }, - apply: banned('Date()'), - }) -} -` - /** Flatten a child's final output blocks to text (the non-schema `agent()` result). */ function outputText(blocks: ContentBlock[]): string { return blocks @@ -167,7 +148,6 @@ export class WorkflowExecution { } this.context = vm.createContext({}, { name: `workflow:${meta.name}` }) - vm.runInContext(DETERMINISM_PRELUDE, this.context) // A run that settles without ever being abandoned leaves `abandoned` // permanently pending or rejecting into the void — consume it so a late // grace timer cannot surface an unhandled rejection. diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index 1dc4833426..eeda6bf049 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -413,16 +413,7 @@ describe('dsh-workflow-vm', () => { }) }) - describe('determinism bans and the value boundary', () => { - it('Date.now, Math.random, and argless new Date throw; parameterized Date stays usable', async () => { - const { ctx, parent } = await setup() - expect((await run(ctx, parent, script('return Date.now()'))).error).toContain('Date.now() is not available') - expect((await run(ctx, parent, script('return Math.random()'))).error).toContain('Math.random() is not available') - expect((await run(ctx, parent, script('return new Date().toISOString()'))).error).toContain('argless new Date()') - const ok = await run(ctx, parent, script('return new Date(0).getTime()')) - expect(ok.value).toBe(0) - }) - + describe('the value boundary', () => { it('args are cloned at start: a script scribbling on them cannot mutate the caller\'s object', async () => { const { ctx, parent } = await setup() const hostArgs = { files: ['a.ts'], nested: { deep: [1, 2] } } From e97fffeab76638f06bfecdde06f21349a62095f1 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 10:05:34 +0800 Subject: [PATCH 034/119] refactor(agent): rename agent/request-messages to agent/request-advice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tianyicui's review: the seam name did not say what the event or its types do. 'advice' reads both ways — advisory content for the model, and AOP before/after advice woven around a join point (here the derived history) without modifying it — so RequestAdvice.before/after are self-describing. Types follow: RequestAdvice / RequestAdviceContext; the logged EpochHeader fields keep their positional names (messagePrefix/messageSuffix). Also sharpens the core.md wording the review flagged as ambiguous: before-advice sits in front of the ENTIRE derived history, directly after the system slot (the conventional home for session-stable openers — an AGENTS.md digest, a skills catalog), after-advice follows the history's last message. Catalogs and doc graphs regenerated. --- docs/architecture.md | 4 +- docs/cordis-catalog/events.md | 34 +++++------ docs/core-data-structures/core.md | 18 +++--- docs/core-data-structures/session.md | 4 +- docs/event-producer-consumer.md | 24 ++++---- .../2026-07-05-reconstructable-requests.md | 6 +- packages/core/agent-loop/README.md | 4 +- packages/core/agent-loop/src/loop.ts | 41 +++++++------ .../agent-loop/tests/interception.spec.ts | 18 +++--- packages/core/agent/README.md | 2 +- packages/core/agent/src/types.ts | 60 ++++++++++--------- packages/core/session/README.md | 2 +- packages/core/session/src/types.ts | 2 +- packages/support/invariants/src/index.ts | 2 +- scripts/type-equiv.manifest.json | 4 +- 15 files changed, 117 insertions(+), 108 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 18138c41cd..1ba6eb1ef9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -72,7 +72,7 @@ forever: agent/pre-step 'step/start' snapshot the derived messages (the reconstruction boundary) - agent/request (config only) -> agent/request-messages -> log request/header -> llm/stream (frozen) + agent/request (config only) -> agent/request-advice -> log request/header -> llm/stream (frozen) 'assistant/chunk' agent/step-result 'assistant/message' @@ -141,7 +141,7 @@ New behavior should attach to a documented seam; changing the shipped loop requi | Add command execution | implement and register a `ctx.bash` backend | | Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events | | Intercept prompts, requests, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` waterfall | -| Add per-request context that must not become history | contribute request-only messages on `agent/request-messages`; logged on the request header | +| Add per-request context that must not become history | contribute request-only messages on `agent/request-advice`; logged on the request header | | Add UI or editor integration | drive `ctx.agents` and render from `session/event` | | Add durable session state | add a `SessionEventMap` member and render/replay from the log | | Fork a live session | use `ctx.sessions.fork(source, boundary?, childSessionId?)` | diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 0a7895baff..9bd7519d80 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -23,7 +23,7 @@ An agent was registered in the AgentRegistry and is ready to receive messages. Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:308`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:313`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -35,7 +35,7 @@ An agent was disposed and removed from the registry; its fiber and any in-flight Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:315`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:320`](../../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:506`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:512`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -61,7 +61,7 @@ Serial (awaited in registration order), not a waterfall: a listener mutates the Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:393`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:398`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -73,7 +73,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a 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:406`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:411`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -85,11 +85,11 @@ A message entered the agent's inbox (queued or steering). `source` is the resolv 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:333`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:338`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall -Waterfall: shape the step's call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use). Config is ALL a listener shapes here: every request is a pure function of the session log (the reconstructability RFC), so model-visible content flows through the log channels — `inject()`, steering, prompt-submit `additionalContext`, prompt sections via `system-prompt/assemble`, or header-logged request-only messages via agent/request-messages — never through request mutation, and the loop records whatever config the request actually uses as a `request/header*` event before dispatch. The step's messages are already snapshotted when this fires (the `step/start` boundary): an `inject()` from a listener here lands in the log but joins the NEXT request. For surface mutation that must precede the snapshot (compaction), use agent/pre-step. Call `next()` to delegate, or return an LlmCallConfig without it to short-circuit. +Waterfall: shape the step's call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use). Config is ALL a listener shapes here: every request is a pure function of the session log (the reconstructability RFC), so model-visible content flows through the log channels — `inject()`, steering, prompt-submit `additionalContext`, prompt sections via `system-prompt/assemble`, or header-logged request-only messages via agent/request-advice — never through request mutation, and the loop records whatever config the request actually uses as a `request/header*` event before dispatch. The step's messages are already snapshotted when this fires (the `step/start` boundary): an `inject()` from a listener here lands in the log but joins the NEXT request. For surface mutation that must precede the snapshot (compaction), use agent/pre-step. Call `next()` to delegate, or return an LlmCallConfig without it to short-circuit. ```ts cordis-catalog 'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise @@ -97,23 +97,23 @@ Waterfall: shape the step's call configuration — model switching, sampling ove Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:430`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:435`](../../packages/core/agent/src/types.ts) -### `agent/request-messages` — waterfall +### `agent/request-advice` — waterfall -Waterfall: contribute request-ONLY messages around the derived history — a RequestMessages whose `before` messages precede the boundary snapshot in `GenerateOptions.messages` and whose `after` messages follow it. Fires once per step, inside the open step, after the agent/request config waterfall and before the loop logs the request header. This is the seam for per-request advisory context the model must see NOW but that must NOT become durable history (a skills catalog, an environment reminder): contributions are recorded on the request's `request/header*` event (`EpochHeader.messagePrefix` / `messageSuffix`) — never as session messages — so `Session.deriveMessages()` stays untouched and the request remains reconstructable from the log. +Waterfall: weave request-ONLY advice around the derived history — a RequestAdvice whose `before` messages sit in front of the ENTIRE boundary snapshot in `GenerateOptions.messages` and whose `after` messages follow its last message. Fires once per step, inside the open step, after the agent/request config waterfall and before the loop logs the request header. This is the seam for per-request advisory context the model must see NOW but that must NOT become durable history (a skills catalog, an environment reminder): contributions are recorded on the request's `request/header*` event (`EpochHeader.messagePrefix` / `messageSuffix`) — never as session messages — so `Session.deriveMessages()` stays untouched and the request remains reconstructable from the log. -The seed is frozen and empty; a contributing listener returns a NEW RequestMessages extending `await next()` (spread its arrays — never mutate them), so contributions compose across plugins in registration order. The boundary snapshot is already taken when this fires: a `session.append`/`inject()` from a listener here lands in the log but joins the NEXT request — contribute through the returned value, not the session. Call `next()` to delegate, or return a RequestMessages without it to short-circuit. +The seed is frozen and empty; a contributing listener returns a NEW RequestAdvice extending `await next()` (spread its arrays — never mutate them), so contributions compose across plugins in registration order. The boundary snapshot is already taken when this fires: a `session.append`/`inject()` from a listener here lands in the log but joins the NEXT request — contribute through the returned value, not the session. Call `next()` to delegate, or return a RequestAdvice without it to short-circuit. Pick the channel by change frequency (the cost model): a contribution rides the request's uncached tail, re-tokenized at full price on EVERY request it appears in — cheap only while small. Session-FROZEN content belongs in `before`, where it extends the cacheable prefix at zero marginal cost (but changing it mid-session invalidates the provider cache for the entire history after it). A LOW-FREQUENCY change notice belongs in durable history via `agent.inject()` — appended once, prefix-cached thereafter. Reserve `after` for small, frequently refreshed state snapshots, where a durable chain of stale copies would bloat the log and mislead the model. ```ts cordis-catalog -'agent/request-messages'(agent: Agent, turn: number, step: number, messages: RequestMessages, context: RequestMessagesContext, next: () => Promise): Promise +'agent/request-advice'(agent: Agent, turn: number, step: number, advice: RequestAdvice, context: RequestAdviceContext, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:471`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:477`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -125,7 +125,7 @@ The agent's session lifecycle began, fired once before its first turn. `source` Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:348`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -137,7 +137,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:324`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:329`](../../packages/core/agent/src/types.ts) ### `agent/step-result` — waterfall @@ -149,7 +149,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:481`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:487`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -161,7 +161,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:494`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:500`](../../packages/core/agent/src/types.ts) ## `fs/*` diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 62dfb41c64..e0d83f435d 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -193,9 +193,9 @@ The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` ### The request envelope: `LlmCallConfig` and the logged header -Requests are built by the loop, not shaped per call: the non-history half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt, assembled tool schemas, and any request-only messages — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling; the `agent/request-messages` waterfall contributes request-only messages framing the derived history (recorded as the header's `messagePrefix`/`messageSuffix`) — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws. +Requests are built by the loop, not shaped per call: the non-history half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt, assembled tool schemas, and any request-only messages — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling; the `agent/request-advice` waterfall weaves request-only advice around the derived history (recorded as the header's `messagePrefix`/`messageSuffix`) — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws. -On the wire, a loop-built request reads in this order: the `system` slot (the rendered prompt assembly) → `messagePrefix` (request-only `before` contributions) → the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps — → `messageSuffix` (request-only `after` contributions, the last thing the model reads). The framing arrays never enter the derived history; their durable record is the header events, and the dev invariant recomputes exactly this equation against every loop-built request. +On the wire, a loop-built request reads in this order: the `system` slot (the rendered prompt assembly) → `messagePrefix` (the request-only `before` advice) → the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps — → `messageSuffix` (the request-only `after` advice, the last thing the model reads). The advice arrays never enter the derived history; their durable record is the header events, and the dev invariant recomputes exactly this equation against every loop-built request. FIXME(call-config-shape): revisit the exact definition of this type — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit here out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them. @@ -328,7 +328,7 @@ interface Agent { } ``` -`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`) is merge-extensible — plugins add creation options by declaration merging; the persona is NOT an agent option but the `dsh-system-prompt` plugin's `persona` config, shared context-wide. The `agent/*` event taxonomy (lifecycle emits incl. `agent/session-start`, the serial `agent/pre-step` surface-mutation seam, and the `agent/prompt-submit`/`agent/request`/`agent/request-messages`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy); turn/step boundaries are durable `session/event` records, not `agent/*` emits. +`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`) is merge-extensible — plugins add creation options by declaration merging; the persona is NOT an agent option but the `dsh-system-prompt` plugin's `persona` config, shared context-wide. The `agent/*` event taxonomy (lifecycle emits incl. `agent/session-start`, the serial `agent/pre-step` surface-mutation seam, and the `agent/prompt-submit`/`agent/request`/`agent/request-advice`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy); turn/step boundaries are durable `session/event` records, not `agent/*` emits. ## Interception decisions @@ -365,21 +365,21 @@ type ContinuationDecision = type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact' ``` -`agent/request-messages` returns a `RequestMessages` — request-only `before`/`after` messages framing the derived history for ONE request. Not a Decision union: the seam contributes content instead of vetoing, so the shape is the contribution itself; the loop records the non-empty arrays as the header's `messagePrefix`/`messageSuffix` ([the request envelope](#the-request-envelope-llmcallconfig-and-the-logged-header)), and `deriveMessages()` never returns them: +`agent/request-advice` returns a `RequestAdvice` — the request-only advice woven around the derived history for ONE request (advice in both senses: advisory content for the model, attached before/after the join point like AOP advice, never modifying the history itself). Concretely, per request: `before` messages sit in front of the ENTIRE derived history, directly after the system slot — the conventional home for session-stable openers like an AGENTS.md digest or a skills catalog, re-contributed identically every step so the provider prefix cache holds; `after` messages follow the history's last message, closing the request. Not a Decision union: the seam contributes content instead of vetoing, so the shape is the contribution itself; the loop records the non-empty arrays as the header's `messagePrefix`/`messageSuffix` ([the request envelope](#the-request-envelope-llmcallconfig-and-the-logged-header)), and `deriveMessages()` never returns them: ```ts type-equiv -interface RequestMessages { - /** Messages placed before the derived history in the request. */ +interface RequestAdvice { + /** Before-advice: messages placed ahead of the entire derived history. */ before: Message[] - /** Messages placed after the derived history in the request. */ + /** After-advice: messages placed after the derived history's last message. */ after: Message[] } ``` -Listeners read the already-fixed request facts from a `RequestMessagesContext` (decide what to contribute from these; never mutate them): +Listeners read the already-fixed request facts from a `RequestAdviceContext` (decide what to contribute from these; never mutate them): ```ts type-equiv -interface RequestMessagesContext { +interface RequestAdviceContext { /** The rendered system prompt this request will carry. */ system: string /** The prompt assembly the system prompt was rendered from (sections + tools). */ diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index ddfa77a9ff..e1f29882e5 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -111,7 +111,7 @@ export interface EpochHeader { tools?: ToolSchema[] /** * Request-only messages sent BEFORE the derived history (the - * `agent/request-messages` waterfall's `before` contributions). Not session + * `agent/request-advice` waterfall's `before` contributions). Not session * history — `deriveMessages()` never returns them — so the header is their * only durable record; absent when the request carried none. */ @@ -121,7 +121,7 @@ export interface EpochHeader { } ``` -Canonical form: an empty system prompt, an empty tool list, and empty request-only message arrays are ABSENT fields, matching how requests are built. `messagePrefix`/`messageSuffix` are the durable record of the `agent/request-messages` waterfall's contributions (the request is `messagePrefix + derived history + messageSuffix`); their deltas replace the array whole, an empty array encoding the transition back to absence. The other delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). +Canonical form: an empty system prompt, an empty tool list, and empty request-only message arrays are ABSENT fields, matching how requests are built. `messagePrefix`/`messageSuffix` are the durable record of the `agent/request-advice` waterfall's contributions (the request is `messagePrefix + derived history + messageSuffix`); their deltas replace the array whole, an empty array encoding the transition back to absence. The other delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). ## `SessionEvent` — one log entry diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 518473a046..d2b0941b2c 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -7,18 +7,18 @@ 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:308`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:315`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:506`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:393`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:406`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:430`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/request-messages` | `waterfall` | [`packages/core/agent/src/types.ts:471`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:348`](../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:324`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:481`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:494`](../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/created` | `emit` | [`packages/core/agent/src/types.ts:313`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:320`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:512`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:398`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:411`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:338`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:435`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/request-advice` | `waterfall` | [`packages/core/agent/src/types.ts:477`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:353`](../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:329`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:487`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:500`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../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:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md index e17679f913..e2bb16438a 100644 --- a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -22,11 +22,11 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro **The header.** The request's non-history half — `EpochHeader`: call config (`LlmCallConfig`: model + sampling scalars), rendered system prompt, assembled tool schemas, and any request-only messages (`messagePrefix`/`messageSuffix`, below) — is logged session state, in canonical form (empty system/tools/message arrays ≡ absent). Two log-only, turn-enclosed events in dsh-session carry it: `request/header`, a full snapshot with reason `'initial' | 'resume' | 'fallback'`, and `request/header-delta`, an amendment (`SystemDelta`: a common-prefix/suffix line trim; `ToolsDelta`: name-keyed added/removed/changed; `config`: replaced whole; `messagePrefix`/`messageSuffix`: replaced whole, an empty array encoding the transition to absence). The pure trio `foldRequestHeader` / `diffHeader` / `applyHeaderDelta` reconstructs; the live session tracks the fold with the same lazy cursor as the message cache. Snapshots anchor the fold where a fold needs anchors — conversation birth and process boundaries — and each loop instance appends one on its first request (`'initial'` when the log has none, `'resume'` otherwise, even when nothing changed: the boundary itself is a recorded fact, and cross-restart drift becomes attributable while an unchanged header resumes byte-identical). Deltas are an encoding optimization with a safety valve, never a correctness dependency: the writer verifies `applyHeaderDelta(prev, delta)` reproduces the new header exactly and records a `'fallback'` snapshot when the encoding cannot express a change (a pure tool reordering), so a well-formed log always folds. -**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → the `agent/request-messages` waterfall — request-ONLY `before`/`after` messages framing the boundary snapshot (a frozen empty seed, contributions returned as an extension of `next()`; the per-request advisory channel: content the model must see now that must NOT become history — a skills catalog, an environment reminder) — → the header event the request owes the log, carrying those contributions as `messagePrefix`/`messageSuffix` (no session event carries them, so the header is their only durable record) → build `GenerateOptions` from `messagePrefix + snapshot + messageSuffix` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's only in-process bookkeeping is one boolean: whether this instance has logged its anchoring snapshot. +**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → the `agent/request-advice` waterfall — request-ONLY `before`/`after` messages framing the boundary snapshot (a frozen empty seed, contributions returned as an extension of `next()`; the per-request advisory channel: content the model must see now that must NOT become history — a skills catalog, an environment reminder) — → the header event the request owes the log, carrying those contributions as `messagePrefix`/`messageSuffix` (no session event carries them, so the header is their only durable record) → build `GenerateOptions` from `messagePrefix + snapshot + messageSuffix` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's only in-process bookkeeping is one boolean: whether this instance has logged its anchoring snapshot. **The reconstruction boundary is `step/start`, unconditionally.** A step's messages are the derivation over `events[0..stepStartSeq)`. Because the snapshot precedes the `step/start` append in the same synchronous frame, nothing can enter this request past the boundary: an `agent.inject()` from an `agent/request` listener (or any concurrent task, or a `session/event` listener firing on `step/start` itself) lands in the log after the boundary and joins the NEXT request. For waterfall-window appends this matches the prior loop (it also derived before its waterfall); for a synchronous `step/start` listener it is a deliberate change — such a listener could previously reach the current request — and `agent/pre-step` is the sanctioned seam for content that must affect the CURRENT request. A step's header for reconstruction is the fold after its own `request/header*` event (which sits between its `step/start` and first response event) or the fold carried forward. -**Enforcement.** Dev-mode ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)), on `llm/stream`: a frozen request with a live `sessionId` — the loop-built marker; hand-built one-shots are unfrozen and skipped — must carry messages deep-equal to the folded header's `messagePrefix`, then the boundary derivation, then its `messageSuffix` — the derivation rebuilt through a FRESH `Session` over `events[0..stepStartSeq)` so the live cache cannot vouch for itself — and header fields equal to `foldRequestHeader` over the log. There is no divergence allowance and nothing to allow: no seam can put unlogged content into a request — the `agent/request-messages` seam's contributions enter only because the header event records them first. `prepend: true` only defends against the replay adapter's short-circuit (an append-registered listener); two prepended listeners have no defined mutual order in cordis, so correctness rests on the seq-bounded fold, never on listener timing. Measurement stays lean: the with-key e2e ([request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts)) proves `usage.cacheReadTokens > 0` on every request after the first against the live API, and per-step usage in the log is the production observable — a header event or compaction shows up as a cache-read collapse on the next step. +**Enforcement.** Dev-mode ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)), on `llm/stream`: a frozen request with a live `sessionId` — the loop-built marker; hand-built one-shots are unfrozen and skipped — must carry messages deep-equal to the folded header's `messagePrefix`, then the boundary derivation, then its `messageSuffix` — the derivation rebuilt through a FRESH `Session` over `events[0..stepStartSeq)` so the live cache cannot vouch for itself — and header fields equal to `foldRequestHeader` over the log. There is no divergence allowance and nothing to allow: no seam can put unlogged content into a request — the `agent/request-advice` seam's contributions enter only because the header event records them first. `prepend: true` only defends against the replay adapter's short-circuit (an append-registered listener); two prepended listeners have no defined mutual order in cordis, so correctness rests on the seq-bounded fold, never on listener timing. Measurement stays lean: the with-key e2e ([request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts)) proves `usage.cacheReadTokens > 0` on every request after the first against the live API, and per-step usage in the log is the production observable — a header event or compaction shows up as a cache-read collapse on the next step. ### The MiniCode shape: adopted, with the provenance arrow inverted @@ -44,7 +44,7 @@ What survives from `LLMClient`: the conversation is maintained, not rebuilt — ## Consequences - A request that is not explained by the log cannot be constructed by accident — not by the loop, not by a listener; mutating a built request throws; every header change is a durable, diffable log event. -- Choosing between the advisory channels is a change-frequency cost decision, and the seam does not hide it: an `agent/request-messages` contribution rides the request's uncached tail and is re-tokenized at full price on every request it appears in (a `before` contribution instead extends the cacheable prefix at zero marginal cost while stable, but a mid-session change invalidates the provider cache for the entire history after it), whereas an `inject()`ed `context/message` is paid once and prefix-cached thereafter at the price of accumulating durably in history and the log. Route session-frozen content to `before`, low-frequency change notices to `inject()`, and reserve `after` for small, frequently refreshed state snapshots where a durable chain of stale copies would bloat the log and mislead the model. +- Choosing between the advisory channels is a change-frequency cost decision, and the seam does not hide it: an `agent/request-advice` contribution rides the request's uncached tail and is re-tokenized at full price on every request it appears in (a `before` contribution instead extends the cacheable prefix at zero marginal cost while stable, but a mid-session change invalidates the provider cache for the entire history after it), whereas an `inject()`ed `context/message` is paid once and prefix-cached thereafter at the price of accumulating durably in history and the log. Route session-frozen content to `before`, low-frequency change notices to `inject()`, and reserve `after` for small, frequently refreshed state snapshots where a durable chain of stale copies would bloat the log and mislead the model. - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replace node), a real prompt/tool change (`request/header-delta`), a config switch (ditto), a process boundary with drift (`'resume'` snapshot differing from its predecessor). The provider's own reasoning-content exclusion is managed server-side. - The `step/start`-listener behavior change (above) is the one observable semantics change for plugins; `agent/pre-step` is the current-request seam. - Tool-result trimming (planned) needs no new mechanism: a logged single-node surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic. diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index 2afa08850a..ebdcc7d91a 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -59,7 +59,7 @@ forever: boundary = session.deriveMessages() ⟵ reconstruction boundary: same sync frame, session('step/start') strictly before step/start config = waterfall agent/request ⟵ frozen seed; return a replacement to switch - reqMsgs = waterfall agent/request-messages ⟵ request-only before/after messages; recorded + reqMsgs = waterfall agent/request-advice ⟵ request-only before/after messages; recorded on the header, never session history session('request/header'[-delta]) ⟵ the header event this request owes the log stream llm.stream(freeze({header..., messages: before+boundary+after})) → session('assistant/chunk') @@ -86,7 +86,7 @@ Cancellation: `agent.cancel()` is the single public stop primitive — it clears ### What is NOT here Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy: -- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/request-messages`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` +- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/request-advice`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` - Compaction: `agent/pre-step` - Sandbox, permission, plan mode: `tools/pre-execute` (deny/ask gate), `tools/post-execute` - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred. diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index b770a34688..9170de4836 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -10,7 +10,7 @@ import type { Context } from 'cordis' import type { FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm' import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm' -import type { ContinuationDecision, HookContext, PromptDecision, RequestMessages } from '@deepseek-ai/dsh-agent' +import type { ContinuationDecision, HookContext, PromptDecision, RequestAdvice } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session' import { createTransmissionLog, recordRequestHeader } from './request-log.ts' @@ -161,7 +161,7 @@ export interface LoopHandle { * boundary = session.deriveMessages() ⟵ the reconstruction boundary: snapshot in the * session('step/start') same sync frame, strictly before step/start * config = waterfall agent/request(config) ⟵ frozen seed; a returned replacement switches - * reqMsgs = waterfall agent/request-messages ⟵ request-only before/after messages; logged on + * advice = waterfall agent/request-advice ⟵ request-only before/after advice; logged on * the header, never session history * session('request/header'|'request/header-delta') ⟵ the header event this request owes the * log (initial/resume anchor, delta, fallback) @@ -720,32 +720,35 @@ async function runStep( throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`) } - // Collect request-ONLY messages: `before` contributions precede the boundary - // snapshot in the request, `after` contributions follow it. They are not - // session history — the header event below is their only durable record - // (EpochHeader.messagePrefix/messageSuffix), which keeps the request a pure - // function of the log. The frozen empty seed serves both the listener chain - // and the no-listener fallback: a contribution is a RETURNED extension of - // `await next()`, never an in-place push. Fired AFTER the boundary snapshot, - // so a listener's session append lands past the boundary and joins the NEXT + // Collect the request-ONLY advice: `before` messages go in front of the + // entire boundary snapshot, `after` messages follow its last message. Advice + // is not session history — the header event below is its only durable + // record (EpochHeader.messagePrefix/messageSuffix), which keeps the request + // a pure function of the log. The frozen empty seed serves both the + // listener chain and the no-listener fallback: a contribution is a RETURNED + // extension of `await next()`, never an in-place push. The context gets a + // frozen COPY of the boundary (the request is built from the internal + // snapshot), so a listener cannot smuggle unlogged content into the request + // by mutating what it was shown. Fired AFTER the boundary snapshot, so a + // listener's session append lands past the boundary and joins the NEXT // request — the same window rule as the `agent/request` waterfall. - const emptyRequestMessages: RequestMessages = deepFreeze({ before: [], after: [] }) - const requestMessagesBoundary = deepFreeze([...boundaryMessages]) - const requestMessages = await ctx.waterfall( - 'agent/request-messages', agent, turn, step, emptyRequestMessages, - { system, assembly, boundaryMessages: requestMessagesBoundary, signal }, - () => Promise.resolve(emptyRequestMessages), + const emptyRequestAdvice: RequestAdvice = deepFreeze({ before: [], after: [] }) + const requestAdviceBoundary = deepFreeze([...boundaryMessages]) + const requestAdvice = await ctx.waterfall( + 'agent/request-advice', agent, turn, step, emptyRequestAdvice, + { system, assembly, boundaryMessages: requestAdviceBoundary, signal }, + () => Promise.resolve(emptyRequestAdvice), ) // The request header (the log's request/header* vocabulary): canonical form, // recorded before dispatch so the log always explains the request — - // including the request-only messages, which no other event carries. + // including the request-only advice, which no other event carries. const header = canonicalHeader({ config, ...system ? { system } : {}, ...assembly.tools.length > 0 ? { tools: assembly.tools } : {}, - ...requestMessages.before.length > 0 ? { messagePrefix: requestMessages.before } : {}, - ...requestMessages.after.length > 0 ? { messageSuffix: requestMessages.after } : {}, + ...requestAdvice.before.length > 0 ? { messagePrefix: requestAdvice.before } : {}, + ...requestAdvice.after.length > 0 ? { messageSuffix: requestAdvice.after } : {}, }) recordRequestHeader(session, transmission, header) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index 14db911a7e..f980b2337c 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -8,7 +8,7 @@ import AgentRegistry, { AgentId, type ContinuationDecision, type PromptDecision, - type RequestMessages, + type RequestAdvice, type SessionStartSource, } from '@deepseek-ai/dsh-agent' import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' @@ -311,7 +311,7 @@ describe('agent/session-start', () => { }) }) -describe('agent/request-messages (RequestMessages)', () => { +describe('agent/request-advice (RequestAdvice)', () => { it('frames the derived history: before precedes it, after follows it, and the header records both', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) @@ -319,7 +319,7 @@ describe('agent/request-messages (RequestMessages)', () => { const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'catalog' }] } const trailer: Message = { role: 'user', content: [{ type: 'text', text: 'trailing note' }] } - ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next): Promise => { + ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next): Promise => { const result = await next() return { before: [...result.before, reminder], after: [...result.after, trailer] } }) @@ -351,7 +351,7 @@ describe('agent/request-messages (RequestMessages)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) const seen: { system: string; boundaryRoles: string[]; sectionCount: number }[] = [] - ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, context, next): Promise => { + ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, context, next): Promise => { const result = await next() seen.push({ system: context.system, @@ -360,7 +360,7 @@ describe('agent/request-messages (RequestMessages)', () => { }) return { before: [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...result.before], after: result.after } }) - ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next): Promise => { + ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next): Promise => { const result = await next() return { before: [...result.before, { role: 'user', content: [{ type: 'text', text: 'second' }] }], after: result.after } }) @@ -385,7 +385,7 @@ describe('agent/request-messages (RequestMessages)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) // A listener that delegates without contributing — the canonical no-op. - ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next) => next()) + ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next) => next()) send(agent, 'hi') await waitForIdle(ctx, agent) @@ -402,7 +402,7 @@ describe('agent/request-messages (RequestMessages)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let mutationError: unknown - ctx.on('agent/request-messages', async (_agent, _turn, _step, messages, _context, next): Promise => { + ctx.on('agent/request-advice', async (_agent, _turn, _step, messages, _context, next): Promise => { try { messages.before.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) } catch (error: unknown) { @@ -424,7 +424,7 @@ describe('agent/request-messages (RequestMessages)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let mutationError: unknown - ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, context, next): Promise => { + ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, context, next): Promise => { try { const mutableBoundary = context.boundaryMessages as Message[] mutableBoundary.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) @@ -454,7 +454,7 @@ describe('agent/request-messages (RequestMessages)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let step = 0 - ctx.on('agent/request-messages', async (_agent, _turn, _step, _messages, _context, next): Promise => { + ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next): Promise => { const result = await next() step += 1 return { before: [...result.before, { role: 'user', content: [{ type: 'text', text: `reminder v${step}` }] }], after: result.after } diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 64a5516761..0500223369 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -45,7 +45,7 @@ Turn and step boundaries are NOT mirrored as `agent/*` emits: a consumer that ne - `agent/prompt-submit` — decide what happens to one drained queued message before it becomes a `user/message`: `PromptDecision` = `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (drop it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`). Maps onto Claude Code's `UserPromptSubmit`. - `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step. - `agent/request` — shape the call config before the model call: a frozen `LlmCallConfig` seed in, a replacement out (model switching, sampling overrides). Content is not shapeable here — every request is a pure function of the session log ([reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)); the loop logs whatever config the request actually uses as a `request/header*` event -- `agent/request-messages` — contribute request-ONLY messages around the derived history: a frozen empty `RequestMessages` seed in, an extension of `await next()` out (`before` messages precede the boundary snapshot in the request, `after` messages follow it). For per-request advisory context the model must see now but that must not become durable history; the loop records the contributions on the request's `request/header*` event (`EpochHeader.messagePrefix`/`messageSuffix`), so `deriveMessages()` stays untouched and the request stays reconstructable. Cost model: contributions ride the request's uncached tail and are re-paid at full price on every request they appear in — put session-frozen content in `before` (cacheable prefix; a mid-session change busts the cache for everything after it), route low-frequency change notices through `agent.inject()` instead (paid once, prefix-cached thereafter), and reserve `after` for small, frequently refreshed state snapshots +- `agent/request-advice` — contribute request-ONLY messages around the derived history: a frozen empty `RequestAdvice` seed in, an extension of `await next()` out (`before` messages precede the boundary snapshot in the request, `after` messages follow it). For per-request advisory context the model must see now but that must not become durable history; the loop records the contributions on the request's `request/header*` event (`EpochHeader.messagePrefix`/`messageSuffix`), so `deriveMessages()` stays untouched and the request stays reconstructable. Cost model: contributions ride the request's uncached tail and are re-paid at full price on every request they appear in — put session-frozen content in `before` (cacheable prefix; a mid-session change busts the cache for everything after it), route low-frequency change notices through `agent.inject()` instead (paid once, prefix-cached thereafter), and reserve `after` for small, frequently refreshed state snapshots - `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records) - `agent/turn-continuation` — override the continue/stop decision via `ContinuationDecision` = `{action:'stop'}` or `{action:'continue', reason?}` (a `continue` `reason` is recorded as next-step steering in the same turn — the typed `/goal` pattern). Force-continue `/loop`, force-stop budget guard. diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 61871f5ad4..c35fc0d84e 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -17,7 +17,7 @@ * consumer that wants the live transcript subscribes here. * - **`agent/*`** (this module) — the LIVE runtime surface. Always carries the * live `Agent`. Two shapes: INTERCEPTION seams (the `agent/prompt-submit`/ - * `agent/request`/`agent/request-messages`/`agent/step-result`/ + * `agent/request`/`agent/request-advice`/`agent/step-result`/ * `agent/turn-continuation` waterfalls and * the serial `agent/pre-step`) that mutate/veto, and TRANSIENT emits * (`agent/status`, `agent/error`, `agent/created`/ @@ -156,34 +156,39 @@ export type ContinuationDecision = | { action: 'continue'; reason?: HookContext } /** - * Request-ONLY messages an `agent/request-messages` waterfall listener - * contributes around the derived history of ONE LLM request: `before` messages - * precede the derived history in `GenerateOptions.messages`, `after` messages - * follow it. They are NOT session events — nothing here enters the session log - * as durable history, `Session.deriveMessages()` never returns them, and the - * next step recomputes them from scratch. The loop records the non-empty - * arrays on the request's `request/header*` event (`EpochHeader.messagePrefix` - * / `messageSuffix`), so the request stays reconstructable from the log (the - * reconstructability RFC). For content that must become durable conversation - * history, use the log channels instead: `agent.inject()`, steering, or - * prompt-submit `additionalContext`. + * The request-only ADVICE an `agent/request-advice` waterfall listener weaves + * around the derived history of ONE LLM request — advice in both senses: + * advisory content for the model, attached before/after the join point like + * AOP advice, never modifying the history itself. In + * `GenerateOptions.messages` the `before` messages sit in front of the ENTIRE + * derived history (directly after the provider's system slot) and the `after` + * messages follow its last message (the newest user prompt on a turn's first + * step, the previous step's tool results afterwards). Advice is NOT session + * state — nothing here enters the session log as durable history, + * `Session.deriveMessages()` never returns it, and the next step recomputes + * it from scratch. The loop records the non-empty arrays on the request's + * `request/header*` event (`EpochHeader.messagePrefix` / `messageSuffix`), so + * the request stays reconstructable from the log (the reconstructability + * RFC). For content that must become durable conversation history, use the + * log channels instead: `agent.inject()`, steering, or prompt-submit + * `additionalContext`. */ -export interface RequestMessages { - /** Messages placed before the derived history in the request. */ +export interface RequestAdvice { + /** Before-advice: messages placed ahead of the entire derived history. */ before: Message[] - /** Messages placed after the derived history in the request. */ + /** After-advice: messages placed after the derived history's last message. */ after: Message[] } /** - * Read-only facts about the request an `agent/request-messages` listener is + * Read-only facts about the request an `agent/request-advice` listener is * contributing to. Everything here is already fixed when the seam fires: the * step is open, the boundary snapshot is taken, and the system prompt is * assembled — a listener uses these to DECIDE what to contribute (e.g. render * a workspace-dependent reminder, or skip one already present in history), * never to mutate them. */ -export interface RequestMessagesContext { +export interface RequestAdviceContext { /** The rendered system prompt this request will carry. */ system: string /** The prompt assembly the system prompt was rendered from (sections + tools). */ @@ -412,7 +417,7 @@ declare module 'cordis' { * session log (the reconstructability RFC), so model-visible content * flows through the log channels — `inject()`, steering, prompt-submit * `additionalContext`, prompt sections via `system-prompt/assemble`, or - * header-logged request-only messages via {@link agent/request-messages} + * header-logged request-only messages via {@link agent/request-advice} * — never through request mutation, and the loop records whatever config * the request actually uses as a `request/header*` event before dispatch. * The step's messages are already snapshotted when this fires (the @@ -429,10 +434,11 @@ declare module 'cordis' { */ 'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise /** - * Waterfall: contribute request-ONLY messages around the derived history — - * a {@link RequestMessages} whose `before` messages precede the boundary - * snapshot in `GenerateOptions.messages` and whose `after` messages follow - * it. Fires once per step, inside the open step, after the + * Waterfall: weave request-ONLY advice around the derived history — a + * {@link RequestAdvice} whose `before` messages sit in front of the + * ENTIRE boundary snapshot in `GenerateOptions.messages` and whose + * `after` messages follow its last message. Fires once per step, inside + * the open step, after the * {@link agent/request} config waterfall and before the loop logs the * request header. This is the seam for per-request advisory context the * model must see NOW but that must NOT become durable history (a skills @@ -443,13 +449,13 @@ declare module 'cordis' { * reconstructable from the log. * * The seed is frozen and empty; a contributing listener returns a NEW - * {@link RequestMessages} extending `await next()` (spread its arrays — + * {@link RequestAdvice} extending `await next()` (spread its arrays — * never mutate them), so contributions compose across plugins in * registration order. The boundary snapshot is already taken when this * fires: a `session.append`/`inject()` from a listener here lands in the * log but joins the NEXT request — contribute through the returned value, * not the session. Call `next()` to delegate, or return a - * {@link RequestMessages} without it to short-circuit. + * {@link RequestAdvice} without it to short-circuit. * * Pick the channel by change frequency (the cost model): a contribution * rides the request's uncached tail, re-tokenized at full price on EVERY @@ -464,11 +470,11 @@ declare module 'cordis' { * @param agent - the agent making the model call. * @param turn - the open turn number. * @param step - the step whose request this is. - * @param messages - the frozen empty seed; return an extended replacement to contribute. - * @param context - read-only request facts ({@link RequestMessagesContext}). + * @param advice - the frozen empty seed; return an extended replacement to contribute. + * @param context - read-only request facts ({@link RequestAdviceContext}). * @mode waterfall */ - 'agent/request-messages'(agent: Agent, turn: number, step: number, messages: RequestMessages, context: RequestMessagesContext, next: () => Promise): Promise + 'agent/request-advice'(agent: Agent, turn: number, step: number, advice: RequestAdvice, context: RequestAdviceContext, next: () => Promise): Promise /** * Waterfall: post-process the assembled assistant {@link Message} before * tool dispatch (validation, content rewriting, …). diff --git a/packages/core/session/README.md b/packages/core/session/README.md index 7fa16d0f3d..f032874cbe 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -51,7 +51,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`. ### Request-header reconstruction (`request-header.ts`) -The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config / whole request-only message arrays) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools/messagePrefix/messageSuffix ≡ absent fields; a delta's EMPTY message array encodes the transition back to absence). `EpochHeader.messagePrefix`/`messageSuffix` are the durable record of the `agent/request-messages` waterfall's request-only contributions — the request is `messagePrefix + derived history + messageSuffix`, and `deriveMessages()` never returns them. +The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config / whole request-only message arrays) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools/messagePrefix/messageSuffix ≡ absent fields; a delta's EMPTY message array encodes the transition back to absence). `EpochHeader.messagePrefix`/`messageSuffix` are the durable record of the `agent/request-advice` waterfall's request-only contributions — the request is `messagePrefix + derived history + messageSuffix`, and `deriveMessages()` never returns them. ### Session event vocabulary (`types.ts`) diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index 052be532bb..75fc84d9a0 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -203,7 +203,7 @@ export interface EpochHeader { tools?: ToolSchema[] /** * Request-only messages sent BEFORE the derived history (the - * `agent/request-messages` waterfall's `before` contributions). Not session + * `agent/request-advice` waterfall's `before` contributions). Not session * history — `deriveMessages()` never returns them — so the header is their * only durable record; absent when the request carried none. */ diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts index 024838ea4c..216049da09 100644 --- a/packages/support/invariants/src/index.ts +++ b/packages/support/invariants/src/index.ts @@ -368,7 +368,7 @@ export function apply(ctx: Context, config: Config = {}): void { // be EXACTLY what the session log reconstructs: // // - messages: the folded header's request-only messages (messagePrefix / - // messageSuffix — the `agent/request-messages` contributions, logged on + // messageSuffix — the `agent/request-advice` contributions, logged on // the header because no session event carries them) framing the // derivation over the log prefix strictly before the in-flight step's // `step/start` (the reconstruction boundary). The derivation is compared diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 7291bee4ca..3f8d0b8bb5 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -15,8 +15,8 @@ { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "RequestMessages", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "RequestMessagesContext", "source": "packages/core/agent/src/types.ts" }, + { "doc": "docs/core-data-structures/core.md", "symbol": "RequestAdvice", "source": "packages/core/agent/src/types.ts" }, + { "doc": "docs/core-data-structures/core.md", "symbol": "RequestAdviceContext", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" }, { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" }, From 8190016e2b099973749a0ccc2153cc6552dff2c5 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 10:06:07 +0800 Subject: [PATCH 035/119] feat(timeout): add tools/execute seam + tool-timeout policy plugin Model-facing tool-call budgets were tangled into each capability's schema (bash timeoutMs, web_fetch timeout_ms) with no shared home. Add a tools/execute around-dispatch waterfall to dsh-tools whose base next() is the dispatch-with-normalization thunk, and a new @deepseek-ai/dsh-timeout-policy plugin (packages/timeout/) that arms a per-tool deadline on exec.signal and returns a structured TOOL_TIMEOUT when it wins. Migrate web_fetch (drop the model-facing timeout_ms) and web_search onto it; the fetch provider keeps its timeout only as a resource backstop for direct callers. bash and hook command execution keep BASH_TIMEOUT unchanged. Named the plugin timeout-policy (not the RFC's tool-timeout) so it does not trip the gen-tool-catalog packages/*/tool-* completeness guard, and replace exec.signal by in-place mutation before next() since cordis waterfall next() ignores passed arguments. RFC moved to implemented/ recording both deviations. --- docs/architecture.md | 2 +- docs/cordis-catalog/events.md | 18 +- docs/cordis-catalog/services.md | 4 +- docs/event-producer-consumer.md | 7 +- docs/module-graph.md | 7 + docs/rfc/INDEX.md | 1 + .../2026-07-07-tool-call-timeout-policy.md | 111 ++++++++ docs/tool-catalog/tools.md | 4 - docs/tool-execution-pipeline.md | 11 +- packages/README.md | 1 + packages/core/tools/README.md | 7 +- packages/core/tools/src/index.ts | 104 +++++--- packages/core/tools/tests/tools.spec.ts | 142 +++++++++++ packages/timeout/README.md | 9 + packages/timeout/timeout-policy/README.md | 46 ++++ packages/timeout/timeout-policy/package.json | 39 +++ packages/timeout/timeout-policy/src/index.ts | 137 ++++++++++ .../tests/timeout-policy.spec.ts | 241 ++++++++++++++++++ packages/timeout/timeout-policy/tsconfig.json | 16 ++ packages/web/tool-web/README.md | 4 +- packages/web/tool-web/package.json | 1 + packages/web/tool-web/src/fetch.ts | 18 +- .../web/tool-web/tests/integration.spec.ts | 79 +++++- packages/web/tool-web/tests/tool-web.spec.ts | 33 ++- packages/web/tool-web/tsconfig.json | 1 + packages/web/web-fetch-local/README.md | 8 +- pnpm-lock.yaml | 22 ++ scripts/gen-doc-graphs.ts | 11 +- scripts/gen-module-graph.ts | 1 + tsconfig.base.json | 1 + tsconfig.build.json | 1 + tsconfig.json | 1 + 32 files changed, 1004 insertions(+), 84 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md create mode 100644 packages/timeout/README.md create mode 100644 packages/timeout/timeout-policy/README.md create mode 100644 packages/timeout/timeout-policy/package.json create mode 100644 packages/timeout/timeout-policy/src/index.ts create mode 100644 packages/timeout/timeout-policy/tests/timeout-policy.spec.ts create mode 100644 packages/timeout/timeout-policy/tsconfig.json diff --git a/docs/architecture.md b/docs/architecture.md index ff51688513..d7bb7c48e8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,7 +78,7 @@ forever: 'assistant/message' each tool call: 'tool/call' - tools/pre-execute -> dispatch -> tools/post-execute + tools/pre-execute -> tools/execute -> tools/post-execute 'tool/result' append post-tool context and steering 'step/end' diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 753cf8f4d0..75f704b4a8 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -307,11 +307,23 @@ A tool was registered or unregistered (the available tool set changed). 'tools/change'(): void ``` +Source: [`packages/core/tools/src/index.ts:108`](../../packages/core/tools/src/index.ts) + +### `tools/execute` — waterfall + +Around-dispatch waterfall wrapping the registry's core tool dispatch, between the `tools/pre-execute` gate and the `tools/post-execute` seam. A listener receives `(exec, next)`: call `next()` to delegate to dispatch (returning its ToolExecutionResult, optionally wrapped), or return a replacement result without calling `next()` to short-circuit dispatch. The base `next()` IS the dispatch-with-normalization thunk — a thrown tool (or unknown tool) is already normalized to an `isError` result by the time a listener's `await next()` returns, so a wrapper never sees a raw throw from the tool body. This is the seam a timeout/retry/metrics plugin wraps: it can mutate `exec` (e.g. replace `exec.signal` with a per-call deadline) BEFORE `next()` and inspect the result AFTER. (Cordis `next()` ignores any passed arguments and re-invokes downstream with the shared payload, so a wrapper mutates `exec` in place rather than passing a new object to `next()`.) Multiple listeners compose by registration order — an outer one wraps the inner ones plus dispatch. + +```ts cordis-catalog +'tools/execute'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise +``` + +Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) + Source: [`packages/core/tools/src/index.ts:87`](../../packages/core/tools/src/index.ts) ### `tools/post-execute` — waterfall -Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code's `PostToolUse`). Listeners receive `(exec, result, next)`: call `next()` to delegate to the default (accept unchanged), or return a PostToolDecision to override. The core tool dispatch sits between the two waterfalls as plain code, all inside `execute`'s outer try/catch (and the tool body keeps its own inner try/catch, so a thrown tool still reaches `post-execute` as an `isError` result). +Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code's `PostToolUse`). Listeners receive `(exec, result, next)`: call `next()` to delegate to the default (accept unchanged), or return a PostToolDecision to override. Core tool dispatch runs earlier as the base `next()` of the `tools/execute` waterfall, all inside `execute`'s outer try/catch (and the tool body keeps its own inner try/catch, so a thrown tool still reaches `post-execute` as an `isError` result). ```ts cordis-catalog 'tools/post-execute'(this: ToolRegistry, exec: ToolExecution, result: ToolExecutionResult, next: () => Promise): Promise @@ -319,7 +331,7 @@ Waterfall AFTER a tool runs — where hook plugins inspect the result and accept Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:82`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:103`](../../packages/core/tools/src/index.ts) ### `tools/pre-execute` — waterfall @@ -331,7 +343,7 @@ Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook pl Types: [ToolExecution](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:66`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:67`](../../packages/core/tools/src/index.ts) ## Inherited events (cordis core + loader/hmr/timer) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 0221946118..85f2437b16 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -193,7 +193,7 @@ Source: [`packages/core/system-prompt/src/index.ts:198`](../../packages/core/sys ## `ctx.tools` — `ToolRegistry` -Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly. +Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → `tools/execute` → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly. ```ts cordis-catalog register(definition: ToolDefinition): () => void @@ -204,7 +204,7 @@ async execute(exec: ToolExecution): Promise Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:268`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:289`](../../packages/core/tools/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 24a2793826..31b6b07a8b 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -31,8 +31,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:87`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | -| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:82`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:66`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:108`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | +| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:87`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | +| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:103`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:67`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`. diff --git a/docs/module-graph.md b/docs/module-graph.md index a4e729484d..14f0908a3d 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -55,6 +55,9 @@ flowchart TD pkg_web_search_exa["web-search-exa"] pkg_web_search_perplexity["web-search-perplexity"] end + subgraph group_timeout["packages/timeout"] + pkg_timeout_policy["timeout-policy"] + end subgraph group_todo["packages/todo"] pkg_tool_todo["tool-todo"] end @@ -146,6 +149,9 @@ flowchart TD pkg_tool_web --> pkg_system_prompt pkg_tool_web --> pkg_tools pkg_tool_web --> pkg_web + pkg_timeout_policy --> pkg_llm + pkg_timeout_policy --> pkg_timeout + pkg_timeout_policy --> pkg_tools pkg_tool_todo --> pkg_agent pkg_tool_todo --> pkg_session pkg_tool_todo --> pkg_tools @@ -240,6 +246,7 @@ flowchart TD | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) | | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | +| [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index b88c40e748..2dcf9d8ba3 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -120,6 +120,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 | | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 | | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 | +| [Tool-call timeout policy as a plugin](implemented/architecture/2026-07-07-tool-call-timeout-policy.md) | 2026-07-07 | ### Process diff --git a/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md new file mode 100644 index 0000000000..edde6aca43 --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md @@ -0,0 +1,111 @@ +# RFC: Tool-call timeout policy as a plugin + +Status: implemented + +## Problem + +The [timeout/deadline RFC](2026-07-06-timeout-deadline-library.md) extracted the timing-and-classification primitive into `@deepseek-ai/dsh-timeout`, but timeout policy was still attached to individual capabilities and model-facing schemas. `bash` exposed `timeoutMs`; `web_fetch` exposed `timeout_ms`; `web_search` had no model-facing timeout even though providers already honor `exec.signal`; a future grep/glob tool would either import the timeout library directly or invent its own timeout policy. That is the wrong authoring shape for a plugin SDK: a tool author should normally forward `exec.signal` to the implementation it calls, and deployment policy should decide the budget. + +At the same time, not every timeout in the repo is a model-facing tool-call budget. Hooks execute command hooks by calling `ctx.bash` directly, not through `ctx.tools.execute()`, and the `bash` model tool multiplexes foreground execution, background start, background polling, and hook reuse through the same backend. Moving every timeout into a tool plugin in one step would conflate those paths and risk breaking hook timeout semantics. + +## Decision + +Tool-call timeout is a policy that applies only to model-facing tool execution, in three parts: + +- `@deepseek-ai/dsh-timeout` remains the shared library that owns `deadline()` and `timeoutOf()`. +- `@deepseek-ai/dsh-tools` has an around-dispatch waterfall, `tools/execute`, between `tools/pre-execute` and `tools/post-execute`. +- `@deepseek-ai/dsh-timeout-policy` reads deployment config and wraps configured tool calls by deriving a new `exec.signal`. + +The execution pipeline is: + +```text +ctx.tools.execute(exec) + -> tools/pre-execute + -> tools/execute + -> registry dispatch (the base next()) + -> tool.execute(args, exec) + -> thrown tool errors normalize to ToolExecutionResult + -> tools/post-execute +``` + +The default behavior is conservative: an unconfigured tool receives no `TOOL_TIMEOUT` deadline from the plugin. + +### The `tools/execute` around seam + +`@deepseek-ai/dsh-tools` declares a `tools/execute` waterfall whose base `next()` is the dispatch-with-normalization thunk — the same inner `try`/`catch` that turns a thrown tool (or unknown tool) into an `isError` `ToolExecutionResult`. A listener receives `(exec, next)`: it calls `next()` to delegate to dispatch (returning its result, optionally wrapped) or returns a replacement result to short-circuit dispatch. The whole pipeline still sits inside `execute`'s outer try/catch, so a throwing listener becomes an `isError` result, never a turn failure. + +That the catch is the base `next` — not something outside the waterfall — is load-bearing: when a provider sees the timeout signal and throws its own upstream-abort error, registry dispatch first converts it to a normal error result, and only then can `timeout-policy` replace the final result with `TOOL_TIMEOUT`. + +### The `timeout-policy` plugin + +The plugin is `@deepseek-ai/dsh-timeout-policy`, a function/namespace plugin (`name` / `Config` / `apply`) in the `packages/timeout/` group. Its config is per tool, with no global default and no model override: + +```yaml +- id: timeout-policy + name: '@deepseek-ai/dsh-timeout-policy' + config: + tools: + web_fetch: + timeoutMs: 30000 + web_search: + timeoutMs: 30000 +``` + +`timeoutMs` is required for every configured tool and must be positive finite (validated at `apply`). For a configured tool the listener arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')`, swaps the derived signal onto `exec` for the downstream dispatch, restores the caller's own signal afterward, and returns a structured `TOOL_TIMEOUT` result when `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches. An unconfigured tool delegates unchanged. + +Signal replacement is by **in-place mutation of `exec.signal`**, not by passing a new object to `next()`. Cordis's waterfall `next()` ignores any arguments handed to it and re-invokes downstream listeners with the shared payload array (`vendor/cordis/src/events.ts`), so the documented cordis idiom — mutate the shared object, then delegate — is the only mechanism that reaches dispatch. The plugin restores `exec.signal` to the caller's original in a `finally` so `tools/post-execute` never sees this plugin's (possibly already-aborted) deadline signal. + +`timeout-policy` owns both uses of the `TOOL_TIMEOUT` code: the internal deadline code passed to `deadline()`/`timeoutOf()` (scoped so a nested outer deadline reads as an ordinary cancel) and the structured tool-result error code. Its replacement result is: + +```ts ignore-check +function toolTimeoutResult(callId: CallId, timeoutMs: number): ToolExecutionResult { + return { + callId, + content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }], + isError: true, + error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, + } +} +``` + +This is a cooperative deadline. It does not kill arbitrary work by racing the tool promise; the tool or the capability it calls must honor `exec.signal` and reach quiescence. "Configured" therefore MEANS "cooperative with `exec.signal`", which the plugin README states as its contract. + +No new session event is needed for reconstructability: `TOOL_TIMEOUT` is the final model-facing `tool/result` for that call, so the existing session log already records the content and structured `{ name, code }` error the next model request sees. + +### Existing tool adaptation + +`web_fetch` and `web_search` are migrated. `dsh-tool-web` keeps ownership of their model-facing schemas, and those schemas expose no timeout knob: `web_fetch` dropped its `timeout_ms` parameter to match the reference-agent shape, and `web_search` stays query-only. The tool bodies do not import `@deepseek-ai/dsh-timeout`; they forward `exec.signal` to `ctx.web`. + +`dsh-web-fetch-local` keeps a provider-level timeout (`timeoutMs`/`maxTimeoutMs`) as a large resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments; it owns no model-facing timeout. When a `TOOL_TIMEOUT` signal reaches the fetch provider first, provider-scoped classification treats it as upstream `WEB_ABORTED`, and the outer `tools/execute` wrapper replaces the final tool result with `TOOL_TIMEOUT`. A shipped web-tool deployment configures the provider backstop above the `timeout-policy` budget so the tool-call policy normally wins for model calls. + +`bash` stays on the current backend timeout path. `dsh-tool-bash` continues to expose `timeoutMs` and `run_in_background`; `dsh-bash-local` continues to use `@deepseek-ai/dsh-timeout` for `BASH_TIMEOUT`; hook bridges continue to call `runHook()` and pass `timeoutMs` through `ctx.bash`. This keeps foreground/background/hook behavior stable. + +`read`, `write`, `edit`, `todo_write`, `bash_output`, and `bash_kill` do not opt into tool-call timeout: they are local filesystem or short registry/session operations where a deadline would be best-effort only or unnecessary. + +A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and a deployment configures `timeout-policy` for its budget. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is outside this cut. + +## Alternatives considered + +**Name the plugin `tool-timeout`.** The literal RFC name matched the `gen-tool-catalog` completeness guard's `packages/*/tool-*` glob, which requires every match to register a model-facing tool. This plugin registers none — it is a `tools/execute` wrapper — so a `tool-*` name would either fail `verify-tool-catalog` or force a misleading boot entry. The package is `@deepseek-ai/dsh-timeout-policy` in a new `packages/timeout/` group; the cordis.yml `id` can still be `timeout-policy`. + +**Keep per-tool timeout handling only.** This was the shape for `bash` and `web_fetch`, and it matches Claude Code and Codex for shell commands. It loses for web-style tools because every new timeout-capable tool must choose validation, cap semantics, docs, snapshots, and classification. The plugin centralizes policy and classification while leaving each tool's schema focused on business input. + +**Move all timeout policy out of bash-local immediately.** Cleaner long-term — bash-local would become a pure subprocess executor and all callers would own their deadlines. It loses as the first step because hooks call `ctx.bash` directly and the bash model tool has foreground/background semantics that are not the same tool-call lifetime. Keeping `BASH_TIMEOUT` preserves those paths while tool-call timeout proves itself on simpler tools. + +**Use a global default budget for every tool.** Convenient, but it surprises tool authors: any tool that accidentally runs longer than the global budget would start failing once the plugin loads. Per-tool config makes adoption deliberate. + +**Expose a model-facing `timeout_ms` override.** Claude Code's `WebFetch`/`WebSearch` and Codex's web tools keep timeout out of the model-call shape. A model override would make timeout part of prompt semantics and force schema/argument-stripping rules into `timeout-policy`. Web timeout stays deployment policy only. + +**Let `timeout-policy` match tool arguments itself.** A rule engine such as "disable timeout when `bash.run_in_background` is true" would make the policy plugin know tool-specific argument semantics. Avoided by not migrating bash to tool-call timeout. + +**Use `tools/pre-execute` plus `tools/post-execute` instead of a new around seam.** A pre listener could arm a deadline and mutate `exec.signal`; a post listener could classify and replace. That loses because the deadline lifetime would cross two independent waterfalls: a call-id map, cleanup on every pre-deny/tool-throw/post-throw/dispose path, and ordering rules with every other listener. `tools/pre-execute` is also the allow/deny gate, not an execution wrapper. `tools/execute` gives the timeout one lexical scope: arm, delegate, classify, dispose. + +**Use `Promise.race` to enforce timeouts for non-cooperative tools.** Rejected for the same reason as the timeout-library RFC: it returns control to the caller while the underlying process, fetch, or provider operation may still be running. The plugin only sends a signal; termination remains the implementation's responsibility. + +## Consequences + +- `@deepseek-ai/dsh-tools` gains an around-dispatch surface after the interception seams deliberately split pre/post tool hooks. Its contract is narrow — wrap registry dispatch, not replace the pre-gate or post-result policy — and the base `next()` is dispatch-with-normalization so a wrapper never sees a raw tool throw. +- Multiple `tools/execute` listeners compose by ordinary Cordis waterfall order: a listener that calls `next()` wraps downstream listeners plus dispatch; one that returns without `next()` short-circuits them. A deployment combining timeout with a future retry/sandbox/metrics wrapper chooses semantics by registration order ("timeout covers the whole retry" vs "timeout covers each attempt"). +- Config-only opt-in is a deliberate misconfiguration risk: a deployment can configure a timeout for a tool that does not honor `exec.signal`, and that tool will not stop on timeout. The plugin contract states that "configured" means cooperative; the web tools prove the pattern on tools that already forward the signal. +- During the transition `bash` and the migrated web tools use different timeout paths on purpose: `TOOL_TIMEOUT` is the model-facing tool-call budget, while `BASH_TIMEOUT` remains the bash backend timeout used by bash and hooks. +- Deviation from the literal proposal, recorded per the implemented-RFC rule: the plugin package is `@deepseek-ai/dsh-timeout-policy` (not `tool-timeout`), and signal replacement is in-place `exec.signal` mutation before `next()` (not `next({ ...exec, signal })`, which cordis ignores). Both are described in `## Decision` above. diff --git a/docs/tool-catalog/tools.md b/docs/tool-catalog/tools.md index 17b4295eda..9bc32ffb4c 100644 --- a/docs/tool-catalog/tools.md +++ b/docs/tool-catalog/tools.md @@ -289,10 +289,6 @@ Fetch the content of a specific HTTP(S) URL and return it decoded to text. "url": { "type": "string", "description": "The HTTP(S) URL to fetch." - }, - "timeout_ms": { - "type": "number", - "description": "Optional fetch timeout in milliseconds (capped by the provider)." } }, "required": [ diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md index db50a3beec..c28c934ab2 100644 --- a/docs/tool-execution-pipeline.md +++ b/docs/tool-execution-pipeline.md @@ -3,7 +3,7 @@ # Tool Execution Pipeline -This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, and UI rendering fit without changing the loop. The key extension points are the `tools/pre-execute` and `tools/post-execute` waterfalls. +This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, and UI rendering fit without changing the loop. The key extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls. ```mermaid flowchart TD @@ -12,6 +12,7 @@ flowchart TD presentCall["UI pending card
presentCall(args)"] pre["tools/pre-execute waterfall
hooks, permission, sandbox"] denied["deny or ask
tool body skipped"] + around["tools/execute waterfall
timeout, retry, metrics (around dispatch)"] toolBody["Registered tool execute() body"] fsGate["fs/write-intent or fs/edit-intent
tool-fs mutations only"] owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result"] @@ -22,18 +23,20 @@ flowchart TD model --> toolCall toolCall --> presentCall toolCall --> pre - pre -->|allow| toolBody + pre -->|allow| around + around --> toolBody pre -->|deny or ask| denied denied --> post toolBody --> fsGate fsGate --> toolBody toolBody --> owned - toolBody --> post + toolBody --> around + around --> post post --> context post --> toolResult toolResult --> presentResult ``` -Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. +Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and future permission prompts live on the generic pre/post tool waterfalls; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs. diff --git a/packages/README.md b/packages/README.md index f07e0d5a36..333dff991f 100644 --- a/packages/README.md +++ b/packages/README.md @@ -15,6 +15,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface | +| [`timeout/`](timeout/README.md) | Tool-call timeout policy: a `tools/execute` wrapper arming a per-tool deadline on `exec.signal` | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 65039aea58..2f19db0b3e 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -1,6 +1,6 @@ # dsh-tools -Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the allow/deny gate) → core dispatch → `tools/post-execute` (inspect/replace the result, attach context). +Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the allow/deny gate) → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context). ## Service: `ToolRegistry` (ctx key: `tools`) @@ -9,7 +9,7 @@ Tool registry and execution pipeline. Tool plugins register their schemas and ex - `ctx.tools.register(definition: ToolDefinition): () => void` Register a tool. Disposed with the calling fiber. - `ctx.tools.get(name: string): ToolDefinition | undefined` - `ctx.tools.schemas(): ToolSchema[]` Schemas of all registered tools (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog/tools.md](../../../docs/tool-catalog/tools.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.execute(exec: ToolExecution): Promise` Execute one tool call through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. +- `ctx.tools.execute(exec: ToolExecution): Promise` Execute one tool call through the `tools/pre-execute` → `tools/execute` → `tools/post-execute` pipeline. ### Injected services @@ -20,6 +20,7 @@ Tool registry and execution pipeline. Tool plugins register their schemas and ex | Event | Mode | Purpose | |---|---|---| | `tools/pre-execute` | waterfall | Allow/deny gate BEFORE a tool runs (sandbox, permission, hooks); returns `PreToolDecision` | +| `tools/execute` | waterfall | Around-dispatch wrapper (timeout, retry, metrics): `(exec, next)` → the dispatched `ToolExecutionResult`; `next()` is dispatch-with-normalization | | `tools/post-execute` | waterfall | Inspect/replace the result AFTER a tool runs, attach context; returns `PostToolDecision` | | `tools/change` | emit | A tool was registered or unregistered | @@ -35,7 +36,7 @@ Tool registry and execution pipeline. Tool plugins register their schemas and ex ### Extension points - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically. -- `tools/pre-execute` is the allow/deny gate (sandbox, permission, hooks): listeners receive `(exec, next)` and call `next()` to delegate to the default (allow) or return a `PreToolDecision` to short-circuit; a `deny`/`ask` skips dispatch and yields an `isError` result. `tools/post-execute` is the inspect/transform seam: `(exec, result, next)` → a `PostToolDecision` that can replace content, block with feedback, or attach `additionalContext`. Core dispatch sits between them as plain code; the tool body keeps its own try/catch so a thrown tool still reaches `post-execute` as an `isError`. Both follow the typed-Decision idiom shared with the `agent/*` interception seams (see [`dsh-agent`](../agent/README.md)). +- `tools/pre-execute` is the allow/deny gate (sandbox, permission, hooks): listeners receive `(exec, next)` and call `next()` to delegate to the default (allow) or return a `PreToolDecision` to short-circuit; a `deny`/`ask` skips dispatch and yields an `isError` result. `tools/execute` is the around-dispatch seam (timeout, retry, metrics): listeners receive `(exec, next)` and call `next()` to delegate to core dispatch (returning its `ToolExecutionResult`, optionally wrapped), or return a replacement result to short-circuit dispatch; the base `next()` IS dispatch-with-normalization, so `await next()` already yields an `isError` result for a thrown/unknown tool (never a raw throw). A wrapper mutates `exec` in place before `next()` — e.g. replacing `exec.signal` with a per-call deadline — because cordis `next()` ignores passed arguments. `tools/post-execute` is the inspect/transform seam: `(exec, result, next)` → a `PostToolDecision` that can replace content, block with feedback, or attach `additionalContext`. Core dispatch is the base of the `tools/execute` waterfall; the tool body keeps its own try/catch so a thrown tool still reaches `post-execute` as an `isError`. All follow the typed-Decision idiom shared with the `agent/*` interception seams (see [`dsh-agent`](../agent/README.md)); `@deepseek-ai/dsh-timeout-policy` is the reference `tools/execute` wrapper. - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas. ### Typed tool parameter schemas diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index dd0ed918db..34e37dfa5f 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -1,9 +1,10 @@ /** * Tool registry and execution pipeline. Plugins register tools; the registry * feeds schemas into the system prompt, and `execute()` dispatches each call - * through `tools/pre-execute` (the allow/deny gate) → core dispatch → - * `tools/post-execute` (inspect/replace the result, attach context) for - * sandbox, permission, and hook plugins to gate or transform a call. + * through `tools/pre-execute` (the allow/deny gate) → `tools/execute` (an + * around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` + * (inspect/replace the result, attach context) for sandbox, permission, and hook + * plugins to gate or transform a call. * * @module @deepseek-ai/dsh-tools */ @@ -64,17 +65,37 @@ declare module 'cordis' { * @mode waterfall */ 'tools/pre-execute'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise + /** + * Around-dispatch waterfall wrapping the registry's core tool dispatch, + * between the `tools/pre-execute` gate and the `tools/post-execute` seam. A + * listener receives `(exec, next)`: call `next()` to delegate to dispatch + * (returning its {@link ToolExecutionResult}, optionally wrapped), or return a + * replacement result without calling `next()` to short-circuit dispatch. The + * base `next()` IS the dispatch-with-normalization thunk — a thrown tool (or + * unknown tool) is already normalized to an `isError` result by the time a + * listener's `await next()` returns, so a wrapper never sees a raw throw from + * the tool body. This is the seam a timeout/retry/metrics plugin wraps: it can + * mutate `exec` (e.g. replace `exec.signal` with a per-call deadline) BEFORE + * `next()` and inspect the result AFTER. (Cordis `next()` ignores any passed + * arguments and re-invokes downstream with the shared payload, so a wrapper + * mutates `exec` in place rather than passing a new object to `next()`.) + * Multiple listeners compose by registration order — an outer one wraps the + * inner ones plus dispatch. + * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal). + * @mode waterfall + */ + 'tools/execute'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise /** * Waterfall AFTER a tool runs — where hook plugins inspect the result and * accept it (optionally REPLACING the model-facing content, and/or attaching * `additionalContext` for the next request) or block it with corrective * `feedback` (Claude Code's `PostToolUse`). Listeners receive * `(exec, result, next)`: call `next()` to delegate to the default (accept - * unchanged), or return a {@link PostToolDecision} to override. The core tool - * dispatch sits between the two waterfalls as plain code, all inside - * `execute`'s outer try/catch (and the tool body keeps its own inner - * try/catch, so a thrown tool still reaches `post-execute` as an `isError` - * result). + * unchanged), or return a {@link PostToolDecision} to override. Core tool + * dispatch runs earlier as the base `next()` of the `tools/execute` + * waterfall, all inside `execute`'s outer try/catch (and the tool body keeps + * its own inner try/catch, so a thrown tool still reaches `post-execute` as an + * `isError` result). * @param exec - the call that just ran (name, parsed arguments, caller agent). * @param result - the dispatch outcome a listener may accept, replace, or block. * @mode waterfall @@ -261,7 +282,7 @@ function errorInfo(error: unknown): ToolErrorInfo | undefined { /** * Tool registry (`ctx.tools`): tool plugins register definitions; the agent - * loop executes calls through the `tools/pre-execute` → dispatch → + * loop executes calls through the `tools/pre-execute` → `tools/execute` → * `tools/post-execute` pipeline. The registry contributes its schemas into the * system-prompt assembly. */ @@ -335,18 +356,20 @@ export class ToolRegistry extends Service { } /** - * Execute one tool call through the `tools/pre-execute` → dispatch → - * `tools/post-execute` pipeline. The two waterfalls are the gate (allow/deny) - * and the inspect/transform seam; core dispatch sits between them as plain - * code. The whole thing is wrapped in one outer try/catch so a throwing - * listener (in either waterfall) becomes an `isError` result instead of - * failing the turn; the tool body ALSO keeps its own inner try/catch, so a - * thrown tool becomes an `isError` result that `post-execute` listeners can - * still inspect. If the tool is not registered, the result is an `isError` - * carrying a `UNKNOWN_TOOL` structured error. A thrown {@link HarnessError} - * surfaces its `{ name, code }` on the result. + * Execute one tool call through the `tools/pre-execute` → `tools/execute` + * (around dispatch) → `tools/post-execute` pipeline. `pre-execute` is the gate + * (allow/deny), `tools/execute` wraps core dispatch (a timeout/retry/metrics + * seam), and `post-execute` is the inspect/transform seam; core dispatch sits + * as the base `next()` of the `tools/execute` waterfall. The whole thing is + * wrapped in one outer try/catch so a throwing listener (in any waterfall) + * becomes an `isError` result instead of failing the turn; the tool body ALSO + * keeps its own inner try/catch, so a thrown tool becomes an `isError` result + * that `tools/execute` and `post-execute` listeners can still inspect. If the + * tool is not registered, the result is an `isError` carrying a `UNKNOWN_TOOL` + * structured error. A thrown {@link HarnessError} surfaces its `{ name, code }` + * on the result. * @param exec - the call to run (name, parsed arguments, caller agent, signal). - * @returns the final result after both waterfalls; failures resolve as + * @returns the final result after every waterfall; failures resolve as * `isError` results, never rejections. */ async execute(exec: ToolExecution): Promise { @@ -372,23 +395,30 @@ export class ToolRegistry extends Service { return await this.postExecute(exec, denied) } - // --- Core dispatch (plain code between the waterfalls). The tool body's - // own try/catch turns a throw into an isError result so post-execute can - // inspect it; an unknown tool routes through the same catch. --- - let result: ToolExecutionResult - try { - const tool = this.store.get(exec.name) - 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 - result = { callId: exec.callId, content, isError: false, ...meta !== undefined ? { meta } : {} } - } catch (error: unknown) { - result = toolErrorResult(exec.callId, error) - } + // --- 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 mutate `exec` before + // delegating and inspect the normalized result after. --- + const result = await this.ctx.waterfall( + this, 'tools/execute', exec, + async (): Promise => { + try { + const tool = this.store.get(exec.name) + 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 { callId: exec.callId, content, isError: false, ...meta !== undefined ? { meta } : {} } + } catch (error: unknown) { + return toolErrorResult(exec.callId, error) + } + }, + ) return await this.postExecute(exec, result) } catch (error: unknown) { diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts index 09158b8398..5207915df8 100644 --- a/packages/core/tools/tests/tools.spec.ts +++ b/packages/core/tools/tests/tools.spec.ts @@ -272,6 +272,148 @@ describe('ToolRegistry', () => { expect(order).toEqual(['pre:before', 'pre:after', 'post:before', 'post:after']) }) + it('runs tools/execute after an allowed pre-execute, around dispatch, and before post-execute', async () => { + const ctx = await setup() + const order: string[] = [] + ctx.tools.register(defineTool({ + name: 'traced', + description: 'echo', + parameters: { text: { type: 'string' } }, + async execute(args) { + order.push('dispatch') + return [{ type: 'text' as const, text: args.text ?? '' }] + }, + })) + + ctx.on('tools/pre-execute', async (_exec, next) => { order.push('pre'); return next() }) + ctx.on('tools/execute', async (_exec, next) => { + order.push('execute:before') + const result = await next() + order.push('execute:after') + return result + }) + ctx.on('tools/post-execute', async (_exec, _result, next) => { order.push('post'); return next() }) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'traced', arguments: { text: 'hi' } }) + expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'hi' }], isError: false }) + // The around seam wraps dispatch; pre gates before it, post runs over its result. + expect(order).toEqual(['pre', 'execute:before', 'dispatch', 'execute:after', 'post']) + }) + + it('a pre-execute deny short-circuits before tools/execute (the seam never runs)', async () => { + const ctx = await setup() + ctx.tools.register(echoTool) + + let entered = false + ctx.on('tools/pre-execute', async (_exec, _next): Promise => ({ kind: 'deny', reason: 'nope' })) + ctx.on('tools/execute', async (_exec, next) => { entered = true; return next() }) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } }) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: nope' }) + expect(entered).toBe(false) // a denied call never enters the around-dispatch seam + }) + + it('a thrown tool is normalized to an isError result BEFORE a tools/execute listener sees next()', async () => { + const ctx = await setup() + ctx.tools.register({ + ...echoTool, + name: 'boom', + async execute() { throw new HarnessError('kaboom', 'BOOM') }, + }) + + let seen: { isError: boolean; error?: unknown } | undefined + ctx.on('tools/execute', async (_exec, next) => { + const result = await next() + // The base next() IS dispatch-with-normalization: the wrapper sees the + // normalized isError result, never a raw throw from the tool body. + seen = { isError: result.isError, error: result.error } + return result + }) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'boom', arguments: {} }) + expect(seen).toEqual({ isError: true, error: { name: 'HarnessError', code: 'BOOM' } }) + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: kaboom' }) + }) + + it('a thrown tool normalized inside tools/execute still reaches post-execute', async () => { + const ctx = await setup() + ctx.tools.register({ + ...echoTool, + name: 'boom', + async execute() { throw new Error('exploded') }, + }) + + let postSaw: boolean | undefined + ctx.on('tools/execute', async (_exec, next) => next()) + ctx.on('tools/post-execute', async (_exec, result, next) => { + postSaw = result.isError + return next() + }) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'boom', arguments: {} }) + expect(postSaw).toBe(true) // the normalized isError still flows through post-execute + expect(result.isError).toBe(true) + expect(result.content[0]).toMatchObject({ text: 'Error: exploded' }) + }) + + it('a tools/execute listener can replace exec.signal for the dispatched tool (deadline pattern)', async () => { + const ctx = await setup() + let seenSignal: AbortSignal | undefined + ctx.tools.register({ + ...echoTool, + name: 'signal-probe', + async execute(_args, exec) { + seenSignal = exec.signal + return [{ type: 'text' as const, text: 'ok' }] + }, + }) + + const upstream = new AbortController().signal + const replacement = new AbortController().signal + ctx.on('tools/execute', async (exec, next) => { + expect(exec.signal).toBe(upstream) + // Cordis next() ignores passed arguments, so a wrapper mutates exec in + // place (the documented "mutate the shared object, then delegate" idiom). + exec.signal = replacement + return next() + }) + + await ctx.tools.execute({ callId: CallId('c1'), name: 'signal-probe', arguments: {}, signal: upstream }) + expect(seenSignal).toBe(replacement) // dispatch saw the wrapper's replacement, not the upstream + }) + + it('a tools/execute listener can short-circuit dispatch by returning a result without next()', async () => { + const ctx = await setup() + let dispatched = false + ctx.tools.register({ + ...echoTool, + name: 'never-runs', + async execute() { dispatched = true; return [] }, + }) + + ctx.on('tools/execute', async (exec, _next): Promise => + ({ callId: exec.callId, content: [{ type: 'text', text: 'short-circuited' }], isError: false })) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'never-runs', arguments: {} }) + expect(dispatched).toBe(false) // returning without next() skips core dispatch + expect(result.content[0]).toMatchObject({ text: 'short-circuited' }) + }) + + it('returns an isError result when a tools/execute listener throws', async () => { + const ctx = await setup() + ctx.tools.register(echoTool) + ctx.on('tools/execute', async () => { throw new Error('wrapper broke') }) + + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } }) + expect(result).toEqual({ + callId: CallId('c1'), + content: [{ type: 'text', text: 'Error: wrapper broke' }], + isError: true, + }) + }) + it('returns an isError result when a tools/pre-execute listener throws', async () => { const ctx = await setup() ctx.tools.register(echoTool) diff --git a/packages/timeout/README.md b/packages/timeout/README.md new file mode 100644 index 0000000000..36f52abaf3 --- /dev/null +++ b/packages/timeout/README.md @@ -0,0 +1,9 @@ +# timeout/ — tool-call timeout policy + +The tool-call timeout policy plugin. A single **product** package: it is a deployment-policy consumer of the `tools/execute` around-dispatch seam (owned by [`dsh-tools`](../core/tools)) and the pure [`dsh-timeout`](../util/timeout) library — not a swappable capability with an interface/implementation split, so it needs no seam trio. + +| Package | Role | ctx key | +|---|---|---| +| `timeout-policy/` | A `tools/execute` wrapper: for each configured tool it arms a per-call deadline on `exec.signal` and returns a structured `TOOL_TIMEOUT` result when that deadline wins | (registers a `tools/execute` listener; injects nothing) | + +Timeout is split across three layers: [`dsh-timeout`](../util/timeout) owns the pure timing/classification primitive (`deadline`/`timeoutOf`), each capability owns termination (bash kills its process group, the fetch provider tears down its socket), and this package owns the *model-facing tool-call budget as deployment policy* — no model-facing timeout argument, no global default. It is the middleware the [timeout-library RFC](../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md) foresaw. `bash` and hook command execution keep their own `BASH_TIMEOUT` backend timeout and do not route through this policy. diff --git a/packages/timeout/timeout-policy/README.md b/packages/timeout/timeout-policy/README.md new file mode 100644 index 0000000000..9054566cc3 --- /dev/null +++ b/packages/timeout/timeout-policy/README.md @@ -0,0 +1,46 @@ +# dsh-timeout-policy + +Tool-call timeout policy: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for each configured tool and returns a structured `TOOL_TIMEOUT` result when that deadline wins. It is the reference `tools/execute` wrapper and the deployment-owned home for model-facing tool-call budgets (the timeout-library RFC's foreseen middleware). + +## Plugin (namespace: `timeout-policy`) + +A function/namespace plugin (`name` / `Config` / `apply`), not a service. It registers no tool and injects nothing — it consumes `ctx.tools`'s `tools/execute` waterfall, which the `dsh-tools` registry always provides. + +### Config + +Per-tool policy, keyed by the model-facing tool name. There is deliberately **no global default** (a global budget would silently start failing any tool that runs long once the plugin loads) and **no model-facing override** (timeout is deployment policy, not prompt semantics) in this version. + +```yaml +- id: timeout-policy + name: '@deepseek-ai/dsh-timeout-policy' + config: + tools: + web_fetch: + timeoutMs: 30000 + web_search: + timeoutMs: 30000 +``` + +| Key | Type | Meaning | +|---|---|---| +| `tools` | `Record` | Per-tool timeout policy; an unlisted tool gets no deadline. `timeoutMs` is required per configured tool and must be positive finite. | + +### Behavior + +For a **configured** tool the listener: + +1. Arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')` — one signal fusing the caller's abort with this plugin's timer (`@deepseek-ai/dsh-timeout`). +2. Swaps that derived signal onto `exec` for the downstream dispatch, then restores the caller's own signal afterward (cordis `next()` ignores passed arguments, so the wrapper mutates the shared `exec` in place; restoring keeps `tools/post-execute` seeing the caller's signal). +3. After dispatch, if `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches — this plugin's own timer fired — replaces the result with a structured `TOOL_TIMEOUT` tool result: `{ isError: true, error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, content: 'Error: tool call timed out after ms' }`. + +An **unconfigured** tool delegates untouched (no deadline). + +The base `next()` of `tools/execute` is the registry's dispatch-with-normalization thunk, so when the timeout signal reaches a provider that throws its own upstream-abort error, dispatch first turns it into a normal error result, and this wrapper then replaces that with `TOOL_TIMEOUT`. That ordering is why the replacement is keyed off the signal (`timeoutOf`), not off the dispatched result's shape. + +### Cooperative, not a hard kill + +The derived signal only **notifies**; termination stays with the tool and the capability it forwards `exec.signal` to (the `dsh-timeout` library owns no kill). **"Configured" therefore means "cooperative with `exec.signal`"**: a tool that ignores the signal will not stop on timeout. A deployment must only configure tools that forward the signal to their implementation — the shipped `web_fetch`/`web_search` (which forward through `ctx.web` to providers) are the reference. `TOOL_TIMEOUT` needs no session event for reconstructability: it is the final model-facing `tool/result`, already logged by the loop. + +### Composing with other `tools/execute` wrappers + +Multiple `tools/execute` listeners compose by cordis registration order. Combined with a future retry/sandbox/metrics wrapper, registration order chooses the semantics — "timeout covers the whole retry operation" (timeout registered outer) versus "timeout covers each attempt" (timeout registered inner). diff --git a/packages/timeout/timeout-policy/package.json b/packages/timeout/timeout-policy/package.json new file mode 100644 index 0000000000..0cf3febc75 --- /dev/null +++ b/packages/timeout/timeout-policy/package.json @@ -0,0 +1,39 @@ +{ + "name": "@deepseek-ai/dsh-timeout-policy", + "description": "Tool-call timeout policy: a tools/execute wrapper that arms a per-tool deadline on exec.signal and returns TOOL_TIMEOUT when it wins", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-timeout": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-timeout": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/timeout/timeout-policy/src/index.ts b/packages/timeout/timeout-policy/src/index.ts new file mode 100644 index 0000000000..5e5b18bb56 --- /dev/null +++ b/packages/timeout/timeout-policy/src/index.ts @@ -0,0 +1,137 @@ +/** + * `@deepseek-ai/dsh-timeout-policy`: the tool-call timeout policy plugin. It + * registers ONE `tools/execute` around-dispatch listener that, for each + * configured tool, arms a per-call deadline on `exec.signal` and returns a + * structured `TOOL_TIMEOUT` result when that deadline wins. + * + * This is a COOPERATIVE deadline, not a hard kill: the derived signal only + * NOTIFIES. A configured tool (and the capability it forwards `exec.signal` to) + * must honor that signal and reach quiescence — the plugin never races the tool + * promise or terminates work itself (see the timeout-library RFC's rejection of + * `Promise.race`). "Configured" therefore MEANS "cooperative with `exec.signal`": + * a tool that ignores the signal will not stop on timeout, so a deployment must + * only list tools that forward it (the shipped web tools are the reference). + * + * Ownership of the `TOOL_TIMEOUT` code is entirely here: it is both the internal + * {@link deadline} code (so {@link timeoutOf} scopes the classification to THIS + * plugin's own timer, reading a foreign/nested outer deadline as an ordinary + * cancel) and the structured `{ name, code }` on the replacement tool result. + * No new session event is needed for reconstructability: the `TOOL_TIMEOUT` + * result IS the final model-facing `tool/result`, already logged by the loop. + * + * Why a `tools/execute` around seam and not a `pre`/`post` pair: the deadline + * needs ONE lexical scope — arm on `exec.signal`, delegate to dispatch, classify + * the result, dispose the timer — which the around seam gives directly. A + * pre/post split would spread one deadline's lifetime across two independent + * waterfalls (a call-id map, cleanup on every deny/throw/dispose path). + * + * @module @deepseek-ai/dsh-timeout-policy + */ + +import type { Context } from 'cordis' +import z from 'schemastery' +import type { CallId } from '@deepseek-ai/dsh-llm' +import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' +import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools' + +/** + * The code owned by this plugin, used BOTH as the internal {@link deadline} + * classification code AND as the structured error `code` on the replacement + * tool result. Scoping {@link timeoutOf} to it keeps a nested outer deadline + * (another `tools/execute` wrapper's timer that fired first) from being misread + * as this plugin's own timeout — it reads as an ordinary upstream cancel. + */ +export const TOOL_TIMEOUT = 'TOOL_TIMEOUT' + +/** Cordis plugin name used by loader diagnostics. */ +export const name = 'timeout-policy' + +/** Per-tool timeout policy. `timeoutMs` is required and must be positive finite. */ +export interface ToolTimeoutPolicy { + /** The per-call cooperative deadline for this tool, in milliseconds. */ + timeoutMs: number +} + +/** + * Plugin config: per-tool timeout policy, keyed by the model-facing tool name. + * There is deliberately NO global default (a global budget would silently start + * failing any tool that happens to run long once the plugin loads) and NO model + * override (timeout is deployment policy, not prompt semantics) in this version. + */ +export interface Config { + /** Timeout policy per tool name; an unlisted tool gets no deadline from this plugin. */ + tools?: Record +} + +export const Config: z = z.object({ + tools: z.dict(z.object({ timeoutMs: z.number() })).default({}), +}) + +/** The shape after schemastery fills `tools` with its `{}` default. */ +type ResolvedConfig = Required + +/** A per-tool timeout must be a positive finite number (0 is not a "disable" value). */ +function assertPositiveFinite(toolName: string, value: number): void { + if (!Number.isFinite(value) || value <= 0) { + throw new Error(`timeout-policy: tools.${toolName}.timeoutMs must be a positive finite number`) + } +} + +/** + * The structured result substituted when this plugin's deadline wins. `content` + * is the model-facing message; `error.code` is the same {@link TOOL_TIMEOUT} + * this plugin owns, so a retry/sandbox plugin (and replay) can route on it. + */ +export function toolTimeoutResult(callId: CallId, timeoutMs: number): ToolExecutionResult { + return { + callId, + content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }], + isError: true, + error: { name: 'ToolTimeoutError', code: TOOL_TIMEOUT }, + } +} + +/** + * Register the tool-call timeout policy. For a configured tool the listener arms + * a {@link deadline} on the caller's `exec.signal`, swaps it onto `exec` for the + * downstream dispatch (cordis `next()` ignores passed arguments, so a wrapper + * mutates the shared `exec` in place), restores the original signal afterward so + * `tools/post-execute` sees the caller's own signal, and replaces the result + * with {@link toolTimeoutResult} when its own timer fired. An unconfigured tool + * delegates untouched. + */ +export function apply(ctx: Context, config: Config): void { + // schemastery (Config) has already filled `tools` with its {} default. + const resolved = config as ResolvedConfig + for (const [toolName, policy] of Object.entries(resolved.tools)) { + assertPositiveFinite(toolName, policy.timeoutMs) + } + + ctx.on('tools/execute', async (exec, next): Promise => { + const timeoutMs = resolved.tools[exec.name]?.timeoutMs + // Unconfigured tool: no deadline, delegate unchanged. + if (timeoutMs === undefined) return next() + + using d = deadline(exec.signal, timeoutMs, TOOL_TIMEOUT) + // Swap the derived deadline onto exec for dispatch, then restore the + // caller's own signal so post-execute listeners never see this plugin's + // (possibly already-aborted) timeout signal. `undefined` is not assignable to + // the optional `signal` under exactOptionalPropertyTypes, so branch on it. + const upstream = exec.signal + exec.signal = d.signal + try { + const result = await next() + // If OUR timer fired (scoped by code — a nested outer deadline reads as + // undefined here), the tool/capability saw the abort and reached + // quiescence; replace whatever it returned (its own abort result) with the + // structured TOOL_TIMEOUT the model sees. + if (timeoutOf(d.signal, TOOL_TIMEOUT) !== undefined) { + return toolTimeoutResult(exec.callId, timeoutMs) + } + return result + } finally { + if (upstream === undefined) delete exec.signal + else exec.signal = upstream + } + }) +} diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts new file mode 100644 index 0000000000..be543f55fa --- /dev/null +++ b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts @@ -0,0 +1,241 @@ +/** + * Unit + real-load-path coverage for @deepseek-ai/dsh-timeout-policy. The + * timeout-wins cases drive the deadline under fake timers (deterministic — no + * wall-clock race) and use a COOPERATIVE tool that settles only when its + * `exec.signal` aborts, mirroring how a real capability forwards the signal and + * reaches quiescence. + */ + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import { CallId, HarnessError } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry, { defineTool, type ToolExecution, type ToolExecutionResult, type PostToolDecision } from '@deepseek-ai/dsh-tools' +import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy' +import { TOOL_TIMEOUT, toolTimeoutResult } from '@deepseek-ai/dsh-timeout-policy' + +/** Mount the registry + the timeout-policy plugin with the given per-tool config. */ +async function setup(tools: Record = {}) { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(timeoutPolicy, { tools }) + return ctx +} + +/** A fast tool: returns immediately, ignoring the signal. */ +const fastTool = defineTool({ + name: 'fast', + description: 'returns at once', + parameters: {}, + async execute() { return [{ type: 'text' as const, text: 'ok' }] }, +}) + +/** A cooperative tool that settles ONLY when its exec.signal aborts (returns text). */ +const cooperativeTool = defineTool({ + name: 'slow', + description: 'stops when aborted', + parameters: {}, + execute(_args, exec): Promise<{ type: 'text'; text: string }[]> { + const done = [{ type: 'text' as const, text: 'stopped cooperatively' }] + if (exec.signal?.aborted) return Promise.resolve(done) + return new Promise((resolve) => { + exec.signal?.addEventListener('abort', () => { resolve(done) }) + }) + }, +}) + +/** A cooperative tool that THROWS its own upstream-abort error when aborted (web-provider shape). */ +const abortThrowingTool = defineTool({ + name: 'aborter', + description: 'throws WEB_ABORTED when aborted', + parameters: {}, + execute(_args, exec): Promise { + if (exec.signal?.aborted) return Promise.reject(new HarnessError('web fetch aborted', 'WEB_ABORTED')) + return new Promise((_resolve, reject) => { + exec.signal?.addEventListener('abort', () => { reject(new HarnessError('web fetch aborted', 'WEB_ABORTED')) }) + }) + }, +}) + +describe('timeout-policy config validation', () => { + it('rejects a non-positive timeout at apply', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await expect(ctx.plugin(timeoutPolicy, { tools: { web_fetch: { timeoutMs: 0 } } })) + .rejects.toThrow('tools.web_fetch.timeoutMs must be a positive finite number') + }) + + it('rejects a non-finite timeout at apply', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await expect(ctx.plugin(timeoutPolicy, { tools: { web_fetch: { timeoutMs: Infinity } } })) + .rejects.toThrow('must be a positive finite number') + }) + + it('mounts with no config (empty tools default) and delegates every call', async () => { + const ctx = await setup() + ctx.tools.register(fastTool) + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} }) + expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }) + }) +}) + +describe('timeout-policy delegation (unconfigured / fast)', () => { + it('delegates an UNCONFIGURED tool unchanged and does not touch exec.signal', async () => { + const ctx = await setup({ other: { timeoutMs: 50 } }) + let seenSignal: AbortSignal | undefined + ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }) + + const upstream = new AbortController().signal + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream }) + expect(result.isError).toBe(false) + expect(seenSignal).toBe(upstream) // no deadline derived for an unconfigured tool + }) + + it('a configured tool that returns fast keeps its own result (no timeout)', async () => { + const ctx = await setup({ fast: { timeoutMs: 10_000 } }) + ctx.tools.register(fastTool) + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} }) + expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }) + }) + + it('a configured tool receives the DERIVED deadline signal (not the caller signal) during dispatch', async () => { + const ctx = await setup({ probe: { timeoutMs: 10_000 } }) + let seenSignal: AbortSignal | undefined + ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }) + + const upstream = new AbortController().signal + await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream }) + expect(seenSignal).toBeDefined() + expect(seenSignal).not.toBe(upstream) // the plugin swapped in its fused deadline signal + }) +}) + +describe('timeout-policy signal restoration', () => { + it('restores the caller signal for post-execute after wrapping', async () => { + const ctx = await setup({ fast: { timeoutMs: 10_000 } }) + ctx.tools.register(fastTool) + let postSignal: AbortSignal | undefined | 'unset' = 'unset' + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { + postSignal = exec.signal + return next() + }) + + const upstream = new AbortController().signal + await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {}, signal: upstream }) + expect(postSignal).toBe(upstream) // restored to the caller's own signal, not the deadline + }) + + it('deletes exec.signal again when the caller passed none', async () => { + const ctx = await setup({ fast: { timeoutMs: 10_000 } }) + ctx.tools.register(fastTool) + let hadSignal: boolean | undefined + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { + hadSignal = 'signal' in exec && exec.signal !== undefined + return next() + }) + + await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} }) + expect(hadSignal).toBe(false) // no caller signal → exec.signal absent again after wrapping + }) +}) + +describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => { + beforeEach(() => { vi.useFakeTimers() }) + afterEach(() => { vi.useRealTimers() }) + + it('replaces a cooperative tool result with TOOL_TIMEOUT when its own deadline fires', async () => { + const ctx = await setup({ slow: { timeoutMs: 100 } }) + ctx.tools.register(cooperativeTool) + + const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'slow', arguments: {} }) + await vi.advanceTimersByTimeAsync(150) // past the 100ms deadline: the timer fires, the tool settles + const result = await pending + + expect(result).toEqual({ + callId: CallId('c1'), + content: [{ type: 'text', text: 'Error: tool call timed out after 100ms' }], + isError: true, + error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, + }) + }) + + it('replaces a provider-owned abort ERROR result with TOOL_TIMEOUT (not WEB_ABORTED) when the signal was ours', async () => { + const ctx = await setup({ aborter: { timeoutMs: 100 } }) + ctx.tools.register(abortThrowingTool) + + const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'aborter', arguments: {} }) + await vi.advanceTimersByTimeAsync(150) + const result = await pending + + // Dispatch first normalized the thrown WEB_ABORTED into an isError result; + // the plugin then replaced THAT with TOOL_TIMEOUT because its own timer won. + expect(result.isError).toBe(true) + expect(result.error).toEqual({ name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }) + expect(result.content[0]).toMatchObject({ text: 'Error: tool call timed out after 100ms' }) + }) + + it('does NOT replace when the caller aborts first (upstream cancel, not our timeout)', async () => { + const ctx = await setup({ slow: { timeoutMs: 100 } }) + ctx.tools.register(cooperativeTool) + + const upstream = new AbortController() + const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'slow', arguments: {}, signal: upstream.signal }) + upstream.abort('user cancelled') // fires before the 100ms timer + await vi.advanceTimersByTimeAsync(0) + const result = await pending + + // Our timer never fired, so timeoutOf(code) is undefined: the tool's own + // cooperative result stands, not a TOOL_TIMEOUT. + expect(result.isError).toBe(false) + expect(result.content[0]).toMatchObject({ text: 'stopped cooperatively' }) + }) +}) + +describe('toolTimeoutResult', () => { + it('builds the structured TOOL_TIMEOUT result', () => { + expect(toolTimeoutResult(CallId('c9'), 250)).toEqual({ + callId: CallId('c9'), + content: [{ type: 'text', text: 'Error: tool call timed out after 250ms' }], + isError: true, + error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, + } satisfies ToolExecutionResult) + }) + + it('exposes the owned code constant', () => { + expect(TOOL_TIMEOUT).toBe('TOOL_TIMEOUT') + }) +}) + +describe('dsh-timeout-policy real-load-path guard', () => { + it('has no default export and keeps name/Config through unwrapExports', () => { + expect('default' in timeoutPolicy).toBe(false) + + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(timeoutPolicy) as Record + expect(unwrapped).toBe(timeoutPolicy) + expect(unwrapped.name).toBe('timeout-policy') + expect(typeof unwrapped.apply).toBe('function') + expect(unwrapped.Config).toBeDefined() + }) + + it('boots over ctx.tools through the unwrapped module and wraps a configured tool', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + ctx.tools.register(fastTool) + + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(timeoutPolicy) as Parameters[0] + const fiber = await ctx.plugin(unwrapped, { tools: { fast: { timeoutMs: 5_000 } } }) + // A configured fast tool still succeeds (deadline never fires); this proves + // the wrapper is live through the real Loader path. + const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} } satisfies ToolExecution) + expect(result.isError).toBe(false) + await fiber.dispose() + }) +}) diff --git a/packages/timeout/timeout-policy/tsconfig.json b/packages/timeout/timeout-policy/tsconfig.json new file mode 100644 index 0000000000..8c0b47716e --- /dev/null +++ b/packages/timeout/timeout-policy/tsconfig.json @@ -0,0 +1,16 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": ["src"], + "references": [ + { "path": "../../../vendor/cosmokit" }, + { "path": "../../../vendor/cordis" }, + { "path": "../../../vendor/schemastery" }, + { "path": "../../llm/llm" }, + { "path": "../../util/timeout" }, + { "path": "../../core/tools" } + ] +} diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md index d8a2e266a9..e99eda5564 100644 --- a/packages/web/tool-web/README.md +++ b/packages/web/tool-web/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-tool-web -The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and `presentCall`. All web access goes through `ctx.web`; this package never imports a concrete provider. +The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and `presentCall`. All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — the tool-call budget is deployment policy owned by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam. Each tool is registered independently; a product that wants only one disables the other via config (`{ search: false }` / `{ fetch: false }`). @@ -9,7 +9,7 @@ Each tool is registered independently; a product that wants only one disables th | Tool | Args | Behavior | |---|---|---| | `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), `timeout_ms` (number, optional) | 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. | +| `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. | ## Config diff --git a/packages/web/tool-web/package.json b/packages/web/tool-web/package.json index 8c22afa9a8..80fd69dbc3 100644 --- a/packages/web/tool-web/package.json +++ b/packages/web/tool-web/package.json @@ -37,6 +37,7 @@ "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", + "@deepseek-ai/dsh-timeout-policy": "workspace:^", "@deepseek-ai/dsh-web": "workspace:^", "@deepseek-ai/dsh-web-fetch-local": "workspace:^", "@deepseek-ai/dsh-web-search-exa": "workspace:^", diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts index 5f7334d952..953a753afb 100644 --- a/packages/web/tool-web/src/fetch.ts +++ b/packages/web/tool-web/src/fetch.ts @@ -3,6 +3,12 @@ * Execution goes through `ctx.web` — this module owns the model-facing schema, * argument validation, and PRESENTATION (HTML→markdown, truncation formatting), * while the fetch provider owns safe retrieval (transport, redirects, caps). + * + * The model-facing schema exposes NO timeout knob: the tool-call budget is + * deployment policy owned by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` + * wrapper), matching the reference-agent `WebFetch` shape. This tool just + * forwards the (possibly deadline-derived) `exec.signal` to `ctx.web`; the + * provider keeps its own timeout only as a resource backstop for direct callers. */ import type { Context } from 'cordis' @@ -15,12 +21,9 @@ import type {} from '@deepseek-ai/dsh-system-prompt' import { htmlToMarkdown } from './html.ts' /** Validate value constraints the schema DSL can't express. */ -export function parseFetchArgs(args: { url: string; timeout_ms?: number }): { url: string; timeoutMs?: number } { +export function parseFetchArgs(args: { url: string }): { url: string } { if (args.url.trim().length === 0) throw new Error('url must be a non-empty string') - if (args.timeout_ms !== undefined && (!Number.isFinite(args.timeout_ms) || args.timeout_ms <= 0)) { - throw new Error('timeout_ms must be a positive number') - } - return { url: args.url, ...args.timeout_ms !== undefined ? { timeoutMs: args.timeout_ms } : {} } + return { url: args.url } } /** Render a fetched body to model-facing markdown text. */ @@ -44,7 +47,7 @@ export function formatFetchOutput(result: WebFetchResult): string { } /** Pending-call presentation: a fetch card titled by the URL. */ -export function presentFetchCall(args: { url: string; timeout_ms?: number }): GenericCallView { +export function presentFetchCall(args: { url: string }): GenericCallView { return { card: 'generic', title: args.url, kind: 'fetch', rawInput: args.url } } @@ -61,12 +64,11 @@ export function applyWebFetchTool(ctx: Context): void { description: 'Fetch the content of a specific HTTP(S) URL and return it decoded to text.', parameters: { url: { type: 'string', required: true, description: 'The HTTP(S) URL to fetch.' }, - timeout_ms: { type: 'number', description: 'Optional fetch timeout in milliseconds (capped by the provider).' }, }, async execute(args, exec): Promise { const input = parseFetchArgs(args) const result = await ctx.web.fetch( - { url: input.url, ...input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {} }, + { url: input.url }, exec.signal ? { signal: exec.signal } : undefined, ) return [{ type: 'text', text: formatFetchOutput(result) }] diff --git a/packages/web/tool-web/tests/integration.spec.ts b/packages/web/tool-web/tests/integration.spec.ts index 50ae6c5624..03ad76ca0f 100644 --- a/packages/web/tool-web/tests/integration.spec.ts +++ b/packages/web/tool-web/tests/integration.spec.ts @@ -1,10 +1,11 @@ /** * Integration: the real fetch backend (`dsh-web-fetch-local`) + a real search * provider (`dsh-web-search-exa`) + the real seam (`dsh-web`) + the model tool - * (`dsh-tool-web`), exercised through `ctx.tools.execute()` — nothing bypasses - * the tool registry. Fetch hits a real loopback HTTP server (verifying the - * WORLD); search runs the real Exa provider over a stubbed global `fetch` (the - * network is the one boundary we mock). + * (`dsh-tool-web`) + the tool-call timeout policy (`dsh-timeout-policy`), + * exercised through `ctx.tools.execute()` — nothing bypasses the tool registry. + * Fetch hits a real loopback HTTP server (verifying the WORLD); search runs the + * real Exa provider over a stubbed global `fetch` (the network is the one + * boundary we mock). */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' @@ -18,6 +19,7 @@ import WebService from '@deepseek-ai/dsh-web' import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local' import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa' import * as ToolWeb from '@deepseek-ai/dsh-tool-web' +import * as TimeoutPolicy from '@deepseek-ai/dsh-timeout-policy' type Handler = (req: IncomingMessage, res: ServerResponse) => void @@ -39,6 +41,9 @@ beforeEach(async () => { await ctx.plugin(WebService, { searchProvider: WebSearchExa.EXA_PROVIDER_ID, fetchProvider: WebFetchLocal.LOCAL_FETCH_PROVIDER_ID }) await ctx.plugin(WebFetchLocal, {}) await ctx.plugin(WebSearchExa, { apiKey: 'exa-key', baseURL: 'https://api.exa.test' }) + // The shipped deployment shape: the tool-call budget is deployment policy over + // the model tools, set above the provider backstop so the policy normally wins. + await ctx.plugin(TimeoutPolicy, { tools: { web_fetch: { timeoutMs: 30_000 }, web_search: { timeoutMs: 30_000 } } }) fiber = await ctx.plugin(ToolWeb) }) @@ -96,3 +101,69 @@ describe('web_search integration over the real Exa provider', () => { expect(out.content.map(b => b.text).join('')).toContain('[Result](https://result.test)') }) }) + +describe('tool-call timeout policy over the migrated web tools', () => { + it('neither model schema exposes a timeout parameter after the migration', () => { + const byName = new Map(ctx.tools.schemas().map(s => [s.name, s])) + const fetchParams = byName.get('web_fetch')!.parameters as { properties: Record } + const searchParams = byName.get('web_search')!.parameters as { properties: Record } + expect(Object.keys(fetchParams.properties)).toEqual(['url']) + expect('timeout_ms' in fetchParams.properties).toBe(false) + expect(Object.keys(searchParams.properties)).toEqual(['query']) + }) +}) + +describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetch)', () => { + let slowServer: Server + let slowBase: string + let openSockets: ServerResponse[] + let tctx: Context + let tfiber: Awaited> + + beforeEach(async () => { + // A server that never responds: it holds the connection open until the + // client aborts. The cooperative deadline (via exec.signal → the fetch + // provider → undici) is what ends the call. + openSockets = [] + slowServer = createServer((_req, res) => { openSockets.push(res) }) + await new Promise(resolve => slowServer.listen(0, '127.0.0.1', resolve)) + slowBase = `http://127.0.0.1:${(slowServer.address() as AddressInfo).port}` + + tctx = new Context() + await tctx.plugin(SystemPrompt) + await tctx.plugin(ToolRegistry) + await tctx.plugin(WebService, { fetchProvider: WebFetchLocal.LOCAL_FETCH_PROVIDER_ID }) + // Provider backstop well ABOVE the tool-call budget, so the policy wins. + await tctx.plugin(WebFetchLocal, { timeoutMs: 30_000, maxTimeoutMs: 60_000 }) + await tctx.plugin(TimeoutPolicy, { tools: { web_fetch: { timeoutMs: 50 } } }) + tfiber = await tctx.plugin(ToolWeb) + }) + + afterEach(async () => { + for (const res of openSockets) res.destroy() + await tfiber.dispose() + await new Promise(resolve => slowServer.close(() => { resolve() })) + }) + + it('returns a structured TOOL_TIMEOUT (not the provider WEB_FETCH_TIMEOUT) when the tool-call budget wins', async () => { + const out = await tctx.tools.execute({ callId: CallId('slow-1'), name: 'web_fetch', arguments: { url: slowBase } }) + expect(out.isError).toBe(true) + // The outer tool-call deadline won: TOOL_TIMEOUT, owned by dsh-timeout-policy, + // NOT the provider's own WEB_FETCH_TIMEOUT (its 30s backstop never fired). + expect(out.error?.code).toBe('TOOL_TIMEOUT') + const text = out.content.map(b => (b.type === 'text' ? b.text : '')).join('') + expect(text).toContain('timed out after 50ms') + }) + + it('the provider backstop still protects a DIRECT ctx.web.fetch() call (no tool-call policy in that path)', async () => { + // A direct seam caller does not go through tools/execute, so the tool-call + // policy never applies; the provider's OWN timeout is the only budget. A + // short per-request hint proves the provider backstop is intact and classifies + // as WEB_FETCH_TIMEOUT (the provider-owned code), never TOOL_TIMEOUT. + const err = await tctx.web.fetch({ url: slowBase, timeoutMs: 50 }).then( + () => undefined, + (e: unknown) => e as { code?: string }, + ) + expect(err?.code).toBe('WEB_FETCH_TIMEOUT') + }) +}) diff --git a/packages/web/tool-web/tests/tool-web.spec.ts b/packages/web/tool-web/tests/tool-web.spec.ts index 924e0aaeb2..e060f90a4c 100644 --- a/packages/web/tool-web/tests/tool-web.spec.ts +++ b/packages/web/tool-web/tests/tool-web.spec.ts @@ -110,10 +110,9 @@ describe('fetch formatting', () => { expect(renderBody({ kind: 'html', content: '

y

' })).toBe('y') }) - it('validates url and timeout', () => { + it('validates url (non-empty), no timeout parameter', () => { expect(() => parseFetchArgs({ url: ' ' })).toThrow('non-empty') - expect(() => parseFetchArgs({ url: 'https://a.test', timeout_ms: -1 })).toThrow('positive') - expect(parseFetchArgs({ url: 'https://a.test', timeout_ms: 5 })).toEqual({ url: 'https://a.test', timeoutMs: 5 }) + expect(parseFetchArgs({ url: 'https://a.test' })).toEqual({ url: 'https://a.test' }) }) it('presents a fetch call as a fetch-kind card titled by the url', () => { @@ -249,7 +248,7 @@ describe('tool-web execution through the real registry', () => { expect('default' in ToolWeb).toBe(false) }) - it('executes web_fetch, forwarding timeout_ms and the abort signal to the seam', async () => { + it('executes web_fetch, forwarding the url (no timeout param) and the abort signal to the seam', async () => { const seen: { request?: { url: string; timeoutMs?: number }; signal?: AbortSignal | undefined } = {} const fetchProvider = { id: 'stub-fetch', @@ -262,13 +261,35 @@ describe('tool-web execution through the real registry', () => { } const { ctx, fiber } = await mountTools({ webConfig: { fetchProvider: 'stub-fetch' }, fetchProvider }) const controller = new AbortController() - const out = await ctx.tools.execute({ callId: CallId('fetch-1'), name: 'web_fetch', arguments: { url: 'https://a.test', timeout_ms: 1234 }, signal: controller.signal }) + const out = await ctx.tools.execute({ callId: CallId('fetch-1'), name: 'web_fetch', arguments: { url: 'https://a.test' }, signal: controller.signal }) expect(out.isError).toBe(false) - expect(seen.request).toEqual({ url: 'https://a.test', timeoutMs: 1234 }) + // The model schema exposes no timeout: the tool forwards only the url; the + // tool-call budget is owned by dsh-timeout-policy over exec.signal. + expect(seen.request).toEqual({ url: 'https://a.test' }) expect(seen.signal).toBe(controller.signal) await fiber.dispose() }) + it('executes web_fetch with no caller signal (forwards undefined to the seam)', async () => { + const seen: { signal?: AbortSignal | undefined; passedExec?: boolean } = {} + const fetchProvider = { + id: 'stub-fetch', + status: () => available, + fetch: (request: { url: string }, exec?: { signal?: AbortSignal }) => { + seen.passedExec = exec !== undefined + seen.signal = exec?.signal + return Promise.resolve({ providerId: 'stub-fetch', url: request.url, statusCode: 200, body: { kind: 'text' as const, content: 'ok' }, truncated: false }) + }, + } + const { ctx, fiber } = await mountTools({ webConfig: { fetchProvider: 'stub-fetch' }, fetchProvider }) + // No signal on the execution: the tool passes `undefined` (not `{ signal: undefined }`). + const out = await ctx.tools.execute({ callId: CallId('fetch-2'), name: 'web_fetch', arguments: { url: 'https://a.test' } }) + expect(out.isError).toBe(false) + expect(seen.passedExec).toBe(false) + expect(seen.signal).toBeUndefined() + await fiber.dispose() + }) + it('executes web_search, forwarding the abort signal to the seam', async () => { const seen: { signal?: AbortSignal | undefined } = {} const provider: WebSearchProvider = { diff --git a/packages/web/tool-web/tsconfig.json b/packages/web/tool-web/tsconfig.json index 463a18dee9..5226425ec6 100644 --- a/packages/web/tool-web/tsconfig.json +++ b/packages/web/tool-web/tsconfig.json @@ -12,6 +12,7 @@ { "path": "../../llm/llm" }, { "path": "../../core/tools" }, { "path": "../../core/system-prompt" }, + { "path": "../../timeout/timeout-policy" }, { "path": "../web" } ] } diff --git a/packages/web/web-fetch-local/README.md b/packages/web/web-fetch-local/README.md index 58db557581..9c2ef0030f 100644 --- a/packages/web/web-fetch-local/README.md +++ b/packages/web/web-fetch-local/README.md @@ -6,7 +6,9 @@ This is an **implementation** package: it registers a provider into `ctx.web`, i ## Responsibility split -The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@deepseek-ai/dsh-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource. +The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, a resource-backstop timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@deepseek-ai/dsh-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource. + +The provider's `timeoutMs`/`maxTimeoutMs` is a **resource backstop** for direct `ctx.web.fetch()` callers and misconfigured deployments — it is NOT the model-facing tool-call budget. The tool-call budget for `web_fetch` is deployment policy owned by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md), which arms a per-call deadline on `exec.signal`. A shipped web-tool deployment sets the provider backstop **above** the `tool-timeout` budget, so the tool-call policy normally wins for model calls (returning `TOOL_TIMEOUT`); when the outer deadline signal reaches this provider first, it classifies as `WEB_ABORTED` and the outer wrapper replaces the result with `TOOL_TIMEOUT`. The provider's own `WEB_FETCH_TIMEOUT` only fires for a direct seam caller whose own budget elapsed. ## Transport hygiene @@ -24,8 +26,8 @@ The provider owns **safe resource retrieval**: URL validation, HTTP transport, r | `maxUrlLength` | `2048` | Maximum accepted request URL length. | | `maxResponseBytes` | `5_000_000` | Maximum response body size in bytes. | | `maxBodyChars` | `100_000` | Maximum decoded body length in characters. | -| `timeoutMs` | `30_000` | Default fetch timeout. | -| `maxTimeoutMs` | `120_000` | Upper bound for a per-request timeout override. | +| `timeoutMs` | `30_000` | Default fetch timeout — a resource backstop for direct `ctx.web.fetch()` callers, not the model-facing tool-call budget (that is `dsh-timeout-policy`). | +| `maxTimeoutMs` | `120_000` | Upper bound for a per-request timeout override (direct callers). | | `maxRedirects` | `5` | Maximum same-origin redirect hops (`0` follows none). | | `userAgent` | `deepseek-harness/…` | `User-Agent` header. | diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 54050bd0f4..b4c2fdc099 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -800,6 +800,25 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/timeout/timeout-policy: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-timeout': + specifier: workspace:^ + version: link:../../util/timeout + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/todo/tool-todo: devDependencies: '@deepseek-ai/dsh-agent': @@ -987,6 +1006,9 @@ importers: '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt + '@deepseek-ai/dsh-timeout-policy': + specifier: workspace:^ + version: link:../../timeout/timeout-policy '@deepseek-ai/dsh-tools': specifier: workspace:^ version: link:../../core/tools diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 4f90b79e8e..c6436bb509 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -621,7 +621,7 @@ function renderToolPipeline(): string { const maintenance = 'curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs' return [ ...generatedHeader('Tool Execution Pipeline'), - 'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, and UI rendering fit without changing the loop. The key extension points are the `tools/pre-execute` and `tools/post-execute` waterfalls.', + 'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, and UI rendering fit without changing the loop. The key extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls.', '', '```mermaid', 'flowchart TD', @@ -630,6 +630,7 @@ function renderToolPipeline(): string { ' presentCall["UI pending card
presentCall(args)"]', ` pre["${mermaidCode('tools/pre-execute')} waterfall
hooks, permission, sandbox"]`, ' denied["deny or ask
tool body skipped"]', + ` around["${mermaidCode('tools/execute')} waterfall
timeout, retry, metrics (around dispatch)"]`, ' toolBody["Registered tool execute() body"]', ` fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}
tool-fs mutations only"]`, ` owned["Tool-owned session events
${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}"]`, @@ -640,19 +641,21 @@ function renderToolPipeline(): string { ' model --> toolCall', ' toolCall --> presentCall', ' toolCall --> pre', - ' pre -->|allow| toolBody', + ' pre -->|allow| around', + ' around --> toolBody', ' pre -->|deny or ask| denied', ' denied --> post', ' toolBody --> fsGate', ' fsGate --> toolBody', ' toolBody --> owned', - ' toolBody --> post', + ' toolBody --> around', + ' around --> post', ' post --> context', ' post --> toolResult', ' toolResult --> presentResult', '```', '', - 'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service.', + 'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and future permission prompts live on the generic pre/post tool waterfalls; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service.', '', ...maintenanceFooter(maintenance), ].join('\n') diff --git a/scripts/gen-module-graph.ts b/scripts/gen-module-graph.ts index b84701c819..fe39d325f8 100644 --- a/scripts/gen-module-graph.ts +++ b/scripts/gen-module-graph.ts @@ -45,6 +45,7 @@ const GROUP_ORDER = [ 'compact', 'subagent', 'web', + 'timeout', 'todo', 'hooks', 'session-persistence', diff --git a/tsconfig.base.json b/tsconfig.base.json index 40e4dbe728..5b2e41509b 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -47,6 +47,7 @@ "./packages/compact/*/src", "./packages/subagent/*/src", "./packages/web/*/src", + "./packages/timeout/*/src", "./packages/todo/*/src", "./packages/hooks/*/src", "./packages/session-persistence/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index ebf8ffef14..1e83e1e47d 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -39,6 +39,7 @@ { "path": "./packages/web/web-search-deepseek" }, { "path": "./packages/web/web-fetch-local" }, { "path": "./packages/web/tool-web" }, + { "path": "./packages/timeout/timeout-policy" }, { "path": "./packages/support/invariants" }, { "path": "./packages/ui/acp" }, { "path": "./packages/ui/acp-agent" }, diff --git a/tsconfig.json b/tsconfig.json index 49cce594dd..512d200193 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -50,6 +50,7 @@ { "path": "./packages/web/web-search-deepseek" }, { "path": "./packages/web/web-fetch-local" }, { "path": "./packages/web/tool-web" }, + { "path": "./packages/timeout/timeout-policy" }, { "path": "./packages/support/invariants" }, { "path": "./packages/ui/acp" }, { "path": "./packages/ui/acp-agent" }, From fb8f20de6e74738bed9c6433ccdde887f9265797 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 10:28:21 +0800 Subject: [PATCH 036/119] fix review findings: reject queued ask aborts --- packages/ui/stdio-agent/src/stdio-chat.ts | 21 ++++++----- .../ui/stdio-agent/tests/stdio-chat.spec.ts | 35 +++++++++++++++++-- 2 files changed, 45 insertions(+), 11 deletions(-) diff --git a/packages/ui/stdio-agent/src/stdio-chat.ts b/packages/ui/stdio-agent/src/stdio-chat.ts index 4745aefb47..8dc402df52 100644 --- a/packages/ui/stdio-agent/src/stdio-chat.ts +++ b/packages/ui/stdio-agent/src/stdio-chat.ts @@ -223,13 +223,10 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt if (activeQuestion !== undefined) return const pending = questionQueue.shift() if (pending === undefined) return - if (pending.request.signal?.aborted) { - pending.reject(new UserInteractionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED')) - startNextQuestion() - return - } + // The queue never contains an aborted pending ask: the seam rejects an + // already-aborted request synchronously, and queued asks attach their + // abort listener before enqueueing. activeQuestion = pending - pending.request.signal?.addEventListener('abort', pending.onAbort, { once: true }) renderQuestion(pending) } @@ -325,11 +322,19 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt resolve, reject, onAbort: () => { - activeQuestion = undefined + if (activeQuestion === pending) { + activeQuestion = undefined + disposeQuestion(pending) + startNextQuestion() + return + } + // If it is not active, this listener can only fire while the ask + // remains queued; settled asks remove the listener first. + questionQueue.splice(questionQueue.indexOf(pending), 1) disposeQuestion(pending) - startNextQuestion() }, } + request.signal?.addEventListener('abort', pending.onAbort, { once: true }) questionQueue.push(pending) startNextQuestion() }) diff --git a/packages/ui/stdio-agent/tests/stdio-chat.spec.ts b/packages/ui/stdio-agent/tests/stdio-chat.spec.ts index 1f4b44e1cf..93683d0768 100644 --- a/packages/ui/stdio-agent/tests/stdio-chat.spec.ts +++ b/packages/ui/stdio-agent/tests/stdio-chat.spec.ts @@ -550,15 +550,44 @@ describe('createStdioChat input', () => { const controller = new AbortController() const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] }) const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal }) - const secondRejected = expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' }) await new Promise(r => setImmediate(r)) controller.abort() + + await expect(Promise.race([ + second.then( + () => 'resolved', + (error: unknown) => (error as { code?: string }).code, + ), + new Promise((resolve) => { setImmediate(() => { resolve('pending') }) }), + ])).resolves.toBe('ASK_ABORTED') + expect(out.text()).not.toContain('\nSecond?\n') input.feed('first answer') + await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] }) + }) + + it('removes an aborted queued question without promoting later queued work early', async () => { + const { ctx, input, out } = await setup() + const controller = new AbortController() + const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] }) + const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal }) + const third = ctx.userInteraction.ask({ questions: [{ id: 'third', question: 'Third?' }] }) + await new Promise(r => setImmediate(r)) + + controller.abort() + + await expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' }) + expect(out.text()).toContain('\nFirst?\n') + expect(out.text()).not.toContain('\nSecond?\n') + expect(out.text()).not.toContain('\nThird?\n') + input.feed('first answer') + await new Promise(r => setImmediate(r)) + + expect(out.text()).toContain('\nThird?\n') + input.feed('third answer') await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] }) - await secondRejected - expect(out.text()).not.toContain('\nSecond?\n') + await expect(third).resolves.toEqual({ answers: [{ id: 'third', selected: [], custom: 'third answer' }] }) }) it('rejects active and queued questions when the UI is disposed', async () => { From 024869177784f0a87806389489d9096d799716ca Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 10:28:47 +0800 Subject: [PATCH 037/119] test: assert timeout-policy listener disposal (codex round 1 P2) Codex flagged that the load-path smoke disposed the fiber only at the end, so a leaked stale tools/execute wrapper would still pass. Add an explicit HMR test: after fiber.dispose(), a configured tool receives the caller's own signal unwrapped (the derived deadline is gone), matching the repo's "dispose must reach quiescence" rule. --- .../tests/timeout-policy.spec.ts | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts index be543f55fa..23017d60f1 100644 --- a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts +++ b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts @@ -211,6 +211,28 @@ describe('toolTimeoutResult', () => { }) }) +describe('timeout-policy disposal (HMR safety)', () => { + it('removes its tools/execute listener when the plugin fiber disposes', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + let seenSignal: AbortSignal | undefined + ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }) + + // Mount the policy on its OWN fiber so disposing it removes only the wrapper. + const fiber = await ctx.plugin(timeoutPolicy, { tools: { probe: { timeoutMs: 10_000 } } }) + const upstream = new AbortController().signal + await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream }) + expect(seenSignal).not.toBe(upstream) // wrapper live: dispatch saw the derived deadline signal + + await fiber.dispose() + // Listener gone: the tool now receives the caller's own signal unwrapped. A + // leaked stale wrapper would still derive a deadline and fail this. + await ctx.tools.execute({ callId: CallId('c2'), name: 'probe', arguments: {}, signal: upstream }) + expect(seenSignal).toBe(upstream) + }) +}) + describe('dsh-timeout-policy real-load-path guard', () => { it('has no default export and keeps name/Config through unwrapExports', () => { expect('default' in timeoutPolicy).toBe(false) From 583704ac1d54674161f5af0990c19d2ea13703e3 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:00:06 +0800 Subject: [PATCH 038/119] feat: add the worker-thread code runtime (dsh-code-runtime-worker) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The shipped backend of the code-execution seam, per the Code Mode RFC's worker-thread section: one fresh Node worker per run, executing the model's TypeScript after a host-side type-strip (wrapped in an async-function shell so top-level return/await parse, sliced back out position-preserved), bindings bridged over the message port under hostile-peer rules (own-property name lookup, at-most-once replies, post-settlement drops, null-prototype namespaces), logs streamed eagerly with an in-band truncation marker, and two independent budgets — measured event-loop busy time (computeMs) plus a never-pausing wall ceiling (maxWallMs) — funneling into worker.terminate(). env: {} and execArgv: [] keep the isolate hermetic; disposal aborts in-flight runs and awaits worker exits. The worker entry loads unbuilt via Node's native type stripping (src/worker.ts, erasable-only) and ships built as a sibling tsdown bundle (lib/worker.js); tests/built-lib.e2e.ts pins the built load path under plain node and joins the built-artifact smoke gate. Unit suites cover the bootstrap in-process (fake port) and the runtime over real workers, per-file 100%. --- AGENTS.md | 4 +- docs/capability-seams.md | 4 +- docs/config-catalog.md | 32 ++ docs/module-graph.md | 3 + docs/testing.md | 2 +- knip.json | 4 + packages/README.md | 2 +- packages/code-runtime/README.md | 5 +- .../code-runtime-worker/README.md | 32 ++ .../code-runtime-worker/package.json | 36 ++ .../code-runtime-worker/src/bootstrap.ts | 257 +++++++++++++ .../code-runtime-worker/src/index.ts | 350 ++++++++++++++++++ .../code-runtime-worker/src/protocol.ts | 65 ++++ .../code-runtime-worker/src/worker.ts | 20 + .../tests/bootstrap.spec.ts | 214 +++++++++++ .../tests/built-lib.e2e.ts | 55 +++ .../code-runtime-worker/tests/runtime.spec.ts | 328 ++++++++++++++++ .../code-runtime-worker/tsconfig.json | 24 ++ .../code-runtime-worker/tsdown.config.ts | 18 + pnpm-lock.yaml | 13 + scripts/check-workspace-constraints.ts | 15 + scripts/gen-doc-graphs.ts | 2 +- scripts/run-gates.ts | 1 + tsconfig.build.json | 1 + tsconfig.json | 1 + vitest.config.ts | 7 +- 26 files changed, 1486 insertions(+), 9 deletions(-) create mode 100644 packages/code-runtime/code-runtime-worker/README.md create mode 100644 packages/code-runtime/code-runtime-worker/package.json create mode 100644 packages/code-runtime/code-runtime-worker/src/bootstrap.ts create mode 100644 packages/code-runtime/code-runtime-worker/src/index.ts create mode 100644 packages/code-runtime/code-runtime-worker/src/protocol.ts create mode 100644 packages/code-runtime/code-runtime-worker/src/worker.ts create mode 100644 packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts create mode 100644 packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts create mode 100644 packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts create mode 100644 packages/code-runtime/code-runtime-worker/tsconfig.json create mode 100644 packages/code-runtime/code-runtime-worker/tsdown.config.ts diff --git a/AGENTS.md b/AGENTS.md index 2cd72aff60..c466a20f77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This is the monorepo of the DeepSeek Harness group; it hosts **DeepSeek Harness SDK**, a plugin-based SDK for building agent harnesses. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; the documentation standard is [docs/AGENTS.md](docs/AGENTS.md). +This is the DeepSeek Harness group's monorepo; it hosts **DeepSeek Harness SDK**, a plugin-based SDK for building agent harnesses. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; the documentation standard is [docs/AGENTS.md](docs/AGENTS.md). ## Pre-release stance: foundation over blast radius @@ -69,7 +69,7 @@ printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})' printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE' ls .sessions/_no-cwd/main-session-*.jsonl >/dev/null rm -rf .sessions -pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts +pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts ``` `test:coverage`, not `test`, is the gating run ([why](docs/testing.md)); a sign-off counts only for commands actually run. diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 339954c00f..12ce8033b9 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -44,6 +44,7 @@ flowchart LR pkg_hooks_codex["hooks-codex"] pkg_code_runtime["code-runtime"] svc_codeRuntime["ctx.codeRuntime
Code-execution seam"] + pkg_code_runtime_worker["code-runtime-worker"] pkg_fs["fs"] svc_fs["ctx.fs
Filesystem provider seam"] pkg_fs_local["fs-local"] @@ -67,6 +68,7 @@ flowchart LR pkg_bash --> svc_bash pkg_bash_local --> svc_bash pkg_code_runtime --> svc_codeRuntime + pkg_code_runtime_worker --> svc_codeRuntime pkg_compact --> svc_compact pkg_compact_basic --> svc_compact pkg_fs --> svc_fs @@ -137,7 +139,7 @@ flowchart LR | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. | -| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | - | - | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer). | +| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | - | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer). | | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. | | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. | | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 73ab7d45dd..6510aea849 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -141,6 +141,38 @@ export interface Config { Source: [`packages/bash/bash-local/src/index.ts:28`](../packages/bash/bash-local/src/index.ts) +## `@deepseek-ai/dsh-code-runtime-worker` + +```ts config-catalog +/** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */ +export interface Config { + /** + * Busy-time budget in milliseconds: the run fails with kind `'timeout'` + * once the worker's MEASURED event-loop active time + * (`worker.performance.eventLoopUtilization()`) exceeds this. Metering + * measured busy time — not wall time, not host-side pending-call + * bookkeeping — is what makes the budget both fair (a program awaiting a + * slow tool accrues nothing) and ungameable (a hot loop accrues whether + * or not a decoy dispatch is in flight). + */ + computeMs?: number + /** + * Wall-clock ceiling in milliseconds; never pauses for anything. The + * backstop for what busy-time cannot see (a program awaiting a promise + * nobody will resolve). + */ + maxWallMs?: number + /** Shared byte budget for captured log text (console + raw stream writes), truncation marked in-band. */ + maxLogBytes?: number + /** Byte cap for the rendered completion value; an oversized or non-cloneable value crosses as a capped string rendering. */ + maxValueBytes?: number + /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */ + maxOldGenerationSizeMb?: number +} +``` + +Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:27`](../packages/code-runtime/code-runtime-worker/src/index.ts) + ## `@deepseek-ai/dsh-compact-basic` Requires: `llm` diff --git a/docs/module-graph.md b/docs/module-graph.md index b12250d484..fa02da2430 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -80,9 +80,11 @@ flowchart TD end subgraph group_code_runtime["packages/code-runtime"] pkg_code_runtime["code-runtime"] + pkg_code_runtime_worker["code-runtime-worker"] end pkg_llm --> pkg_brand pkg_bash --> pkg_brand + pkg_code_runtime_worker --> pkg_code_runtime pkg_llm_deepseek --> pkg_llm pkg_llm_pi_ai --> pkg_llm pkg_session --> pkg_brand @@ -214,6 +216,7 @@ flowchart TD | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — | | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) | | [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand) | +| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime) | | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) | | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) | | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | diff --git a/docs/testing.md b/docs/testing.md index d7ed14ecb9..5ec94b7502 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -25,7 +25,7 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword - A plugin shipped via `cordis.yml` needs at least one test through the REAL Loader path: hand-built `ctx.plugin({...})` mounts bypass `unwrapExports` and cannot catch a broken export shape ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md); export-shape rules in [packages/AGENTS.md](../packages/AGENTS.md)). - 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). Keep the built-bin smokes green (`packages/ui/*/tests/built-bin.e2e.ts`), and assert a genuinely-missing config exits non-zero. +- "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.js`). 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)). ## When a snapshot test is required diff --git a/knip.json b/knip.json index 89cd2fffe7..b9dbd9bbff 100644 --- a/knip.json +++ b/knip.json @@ -25,6 +25,10 @@ "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, + "packages/code-runtime/code-runtime-worker": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"] + }, "packages/llm/llm-deepseek": { "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] diff --git a/packages/README.md b/packages/README.md index da75f740e8..8e918c4c15 100644 --- a/packages/README.md +++ b/packages/README.md @@ -11,7 +11,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`core/`](core/README.md) | Product API spine: session, system-prompt, tools, agent, and the concrete loop | Product — stable surface | | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface | | [`bash/`](bash/README.md) | Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface | -| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs | Product — stable surface | +| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface | | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface | | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md index 578f3179c1..b98baa43e6 100644 --- a/packages/code-runtime/README.md +++ b/packages/code-runtime/README.md @@ -1,9 +1,10 @@ # code-runtime/ — code-execution capability family -The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's Code Mode, and the first implementation (a Node worker-thread backend) is specified alongside it in the [Code Mode RFC](../../docs/rfc/proposed/feature/2026-06-15-code-mode.md). **Product** packages. +The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's Code Mode, specified alongside the seam in the [Code Mode RFC](../../docs/rfc/proposed/feature/2026-06-15-code-mode.md). **Product** packages. | Package | Role | ctx key | |---|---|---| | `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` | +| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip, port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` | -The interface lives at `code-runtime/code-runtime/`. Backends differ by execution substrate (worker thread, process, container) and by source language — both readonly descriptors on the service — and register `ctx.codeRuntime` without touching the interface or its consumer; that split is what makes a hardened backend a drop-in later. +The interface lives at `code-runtime/code-runtime/`; the shipped backend at `code-runtime/code-runtime-worker/`. Backends differ by execution substrate (worker thread, process, container) and by source language — both readonly descriptors on the service — and register `ctx.codeRuntime` without touching the interface or its consumer; that split is what makes a hardened backend a drop-in later. diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md new file mode 100644 index 0000000000..13bf992bb5 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/README.md @@ -0,0 +1,32 @@ +# @deepseek-ai/dsh-code-runtime-worker + +Worker-thread implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam: `WorkerCodeRuntime` runs each program in ONE fresh Node `worker_threads.Worker` — TypeScript in, type-stripped host-side, bindings bridged over the message port, `{ value, logs, error? }` out. **Containment, not a security boundary**: trust posture is bash-equivalent by design (the [Code Mode RFC](../../../docs/rfc/proposed/feature/2026-06-15-code-mode.md) § Trust posture), with containment bash does not have — separate isolate, empty environment, heap cap, hard termination. + +## Config + +```yaml +- id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' + config: + computeMs: 60000 # busy-time budget (measured event-loop active time) + maxWallMs: 600000 # wall-clock ceiling; never pauses for anything + maxLogBytes: 65536 # shared byte budget for captured log text + maxValueBytes: 32768 # rendered-completion-value cap + maxOldGenerationSizeMb: 512 # worker heap cap (resourceLimits) +``` + +Every field is validated (positive numbers) and defaulted; there are no other tunables. + +## Design + +- **One fresh worker per run, no pooling** — a program's world dies with its worker: no cross-run state to log, state bleed unrepresentable, runs reconstructable from the session log alone. +- **Type-strip host-side, in execution context** — the program is wrapped in an async-function shell, stripped with `node:module`'s `stripTypeScriptTypes` (erasable syntax only — `enum`/namespaces are rejected as a program `exception` and no worker spawns), and sliced back out byte-positioned; it then executes as the body of an `AsyncFunction`, so top-level `await`/`return` work. +- **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and converts a non-cloneable binding resolution into an error reply. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys. +- **Two independent budgets, because the peer is hostile** — `computeMs` meters the worker's MEASURED busy time (`worker.performance.eventLoopUtilization()` polling): a hot loop cannot hide behind a pending decoy dispatch, and a program awaiting a slow tool accrues nothing. `maxWallMs` backstops what busy time cannot see (awaiting a promise nobody resolves). Both funnel into `worker.terminate()`, which ends hot synchronous loops too; heap overflow surfaces as the worker's OOM exit (`kind: 'worker-exit'`). +- **Logs stream eagerly** — console/stdout/stderr entries cross the port as they happen, so a timed-out or killed program still shows what it printed; pipe bytes that bypass the patched streams are appended after, under the same byte budget. +- **Empty environment** — the worker gets `env: {}` and `execArgv: []`: no ambient credentials (stronger than the scrubbed-env rule for spawned commands) and no inherited loader flags. +- **Dispose to quiescence** — teardown fails in-flight runs as `abort` and AWAITS each worker's exit before resolving. + +## The worker entry, unbuilt and built + +`worker.ts` is deliberately erasable-only TypeScript with type-only cross-package imports: unbuilt (vitest/tsx), the host spawns `src/worker.ts` directly and Node's native type stripping loads it; built, the entry ships as the sibling bundle `lib/worker.js` (its own tsdown entry). The built path is pinned by `tests/built-lib.e2e.ts`, the real-load-path guard from [docs/testing.md](../../../docs/testing.md). diff --git a/packages/code-runtime/code-runtime-worker/package.json b/packages/code-runtime/code-runtime-worker/package.json new file mode 100644 index 0000000000..85df6a0d78 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/package.json @@ -0,0 +1,36 @@ +{ + "name": "@deepseek-ai/dsh-code-runtime-worker", + "description": "Worker-thread implementation of the DeepSeek Harness code-execution seam", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/worker.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-code-runtime": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-code-runtime": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts new file mode 100644 index 0000000000..06cef02c7b --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts @@ -0,0 +1,257 @@ +/** + * Worker-side execution logic, written as plain functions over an injected + * port so the unit suite can run every line IN-PROCESS against a fake port + * (a real worker thread is a separate V8 isolate the coverage provider + * cannot observe). The real worker entry (`worker.ts`) is a thin + * self-executing glue file over {@link runWorkerMain}, excluded from + * coverage the same way `bin.ts` entrypoints are, and exercised end-to-end + * by the integration tests that spawn real workers. + * + * @module @deepseek-ai/dsh-code-runtime-worker/src/bootstrap + */ + +import { inspect } from 'node:util' +import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime' +import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' + +/** The port surface the bootstrap needs — satisfied by `parentPort` and by the tests' fake. */ +export interface BootstrapPort { + postMessage(message: WorkerToHost): void + on(event: 'message', listener: (message: ReplyMessage) => void): void +} + +/** + * A writable stream's `write` slot, as the bootstrap patches it (see + * {@link captureStreamWrites}). Method-typed so the real + * `process.stdout`/`process.stderr` (narrower chunk parameters) remain + * assignable. + */ +export interface PatchableStream { + write(chunk: unknown, ...rest: unknown[]): boolean +} + +/** + * Ordered log capture under one shared byte budget, delivered to a sink as + * each entry lands (the real sink streams entries over the port eagerly, so + * captured output survives a mid-run termination). Once the budget is + * exhausted it emits exactly one in-band marker entry (on the `stderr` + * diagnostics channel) and silently drops everything after — the cap is a + * blast-radius bound, so "how much was lost" intentionally stays unmeasured. + */ +export class LogBuffer { + private remaining: number + private truncated = false + // Explicit fields, not constructor parameter properties: this module loads + // under Node's native strip-only mode, which rejects non-erasable syntax — + // and parameter properties are non-erasable. + private readonly maxBytes: number + private readonly sink: (entry: CodeLogEntry) => void + + constructor(maxBytes: number, sink: (entry: CodeLogEntry) => void) { + this.maxBytes = maxBytes + this.sink = sink + this.remaining = maxBytes + } + + /** + * Emit one entry to the sink, charging its text against the budget (drops + marks once exhausted). + * @param entry - the log entry to deliver. + */ + push(entry: CodeLogEntry): void { + if (this.truncated) return + const cost = Buffer.byteLength(entry.text, 'utf8') + if (cost > this.remaining) { + this.truncated = true + this.sink({ source: 'stderr', text: `[dsh-code-runtime-worker] log capture truncated at ${this.maxBytes} bytes` }) + return + } + this.remaining -= cost + this.sink(entry) + } +} + +/** The five console methods the shim captures, in the seam's level vocabulary. */ +const CONSOLE_LEVELS = ['log', 'info', 'warn', 'error', 'debug'] as const + +/** + * A `console` replacement whose five leveled methods render their arguments + * `util.inspect`-style (matching real console formatting closely enough for + * a model to recognize its own output) into the buffer. Only these five + * exist — the program gets a deliberately small console, not Node's full + * surface. + * @param logs - the buffer every rendered line is pushed into. + * @returns the five-method console object handed to the program. + */ +export function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS)[number], (...args: unknown[]) => void> { + const render = (args: unknown[]): string => + args.map(arg => typeof arg === 'string' ? arg : inspect(arg, INSPECT_OPTIONS)).join(' ') + const shim = Object.create(null) as Record<(typeof CONSOLE_LEVELS)[number], (...args: unknown[]) => void> + for (const level of CONSOLE_LEVELS) { + shim[level] = (...args: unknown[]) => { logs.push({ source: 'console', level, text: render(args) }) } + } + return shim +} + +/** + * Redirect a stream's `write` into the log buffer (the program-visible + * `process.stdout`/`process.stderr` in the real worker), so raw writes land + * in emission order alongside console output instead of racing down a pipe. + * @param logs - the buffer captured writes are pushed into. + * @param stream - the stream whose `write` slot is patched. + * @param source - the log source the captured writes are attributed to. + * @returns the restore function (the in-process tests un-patch; the real + * worker never needs to). + */ +export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream, source: 'stdout' | 'stderr'): () => void { + // The slot's VALUE is stored for restore and reassigned — never invoked + // detached, so the unbound-method concern does not apply. + // eslint-disable-next-line @typescript-eslint/unbound-method + const original = stream.write + stream.write = (chunk: unknown): boolean => { + logs.push({ source, text: typeof chunk === 'string' ? chunk : String(chunk) }) + return true + } + return () => { stream.write = original } +} + +/** Bounded inspect options: deep enough to be useful, bounded so a pathological value cannot explode the rendering. */ +const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const + +/** + * Prepare the program's completion value for the done message: a + * structured-clone-safe value whose rendering fits `maxValueBytes` crosses + * raw; anything else (non-cloneable, or oversized) is REPLACED by its + * bounded `util.inspect` rendering, truncated with an in-band marker — the + * seam contract's "a non-transferable value is replaced by a string + * rendering", extended to oversized ones so a huge return cannot flood the + * host. + * @param value - the program's completion value. + * @param maxValueBytes - the byte cap for the rendered value. + * @returns the done-message fragment: `{}` for `undefined`, else `{ value }`. + */ +export function prepareValue(value: unknown, maxValueBytes: number): { value?: unknown } { + if (value === undefined) return {} + const rendered = typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS) + let cloneable = true + try { + structuredClone(value) + } catch { + // Only the verdict matters: the value has parts structured clone rejects + // (functions, classes, …) and must cross as its rendering instead. + cloneable = false + } + if (cloneable && Buffer.byteLength(rendered, 'utf8') <= maxValueBytes) return { value } + const capped = rendered.length > maxValueBytes ? `${rendered.slice(0, maxValueBytes)}… [truncated]` : rendered + return { value: capped } +} + +/** One awaited binding call's settlement handles, keyed by call id in the pending map. */ +export interface PendingCall { + resolve(value: unknown): void + reject(error: Error): void +} + +/** + * Route host replies into the pending-call map: each reply settles its call + * at most once, and a reply for an unknown id (stray, or a duplicate answer + * to an id already settled) is ignored. Shared wiring between + * {@link runWorkerMain} and the tests that exercise {@link makeNamespaces} + * standalone. + * @param port - the port whose `message` events carry the replies. + * @param pending - the id-keyed map of unsettled binding calls. + */ +export function wireReplies(port: BootstrapPort, pending: Map): void { + port.on('message', (message: ReplyMessage) => { + const entry = pending.get(message.id) + if (!entry) return + pending.delete(message.id) + if (message.ok) entry.resolve(message.value) + else entry.reject(new Error(message.message)) + }) +} + +/** + * Build the binding namespace objects the program sees: one null-prototype + * global per namespace, each declared name an own enumerable async function + * that bridges over the port (`__proto__`/`constructor`/`toString` are + * ordinary keys, never prototype collisions). A non-cloneable argument + * rejects that one call with a descriptive error; the host's reply (`ok` + * false) rejects it likewise, so a failed tool call surfaces in the program + * as an ordinary promise rejection. + * @param data - the boot payload's namespace declarations (globals + names). + * @param port - the port binding calls are posted to. + * @param pending - the id-keyed map each posted call parks its handles in. + * @param nextId - the shared mutable id counter (worker-issued correlation ids). + * @returns one namespace object per declaration, in declaration order. + */ +export function makeNamespaces( + data: Pick, + port: BootstrapPort, + pending: Map, + nextId: { value: number }, +): Record[] { + return data.namespaces.map(({ global, names }) => { + const namespace = Object.create(null) as Record + for (const name of names) { + Object.defineProperty(namespace, name, { + enumerable: true, + value: (args: unknown): Promise => new Promise((resolve, reject) => { + const id = nextId.value++ + pending.set(id, { resolve, reject }) + try { + port.postMessage({ type: 'call', id, global, name, args }) + } catch (error: unknown) { + pending.delete(id) + reject(new Error(`binding arguments must be structured-cloneable: ${error instanceof Error ? error.message : String(error)}`)) + } + }), + }) + } + return namespace + }) +} + +/** + * Run one program to settlement and post the {@link DoneMessage}: wires the + * reply handler, materializes the namespaces and console shim, compiles the + * type-stripped body as an async function (top-level `await`/`return` + * work), and reports a thrown program error as the done message's `error` + * field. Exactly one done message is ever posted. + * @param port - the message port to the host (the real `parentPort`, or the tests' fake). + * @param data - the boot payload the host sent. + * @param streams - the stream objects whose `write` is captured (the real + * `process.stdout`/`process.stderr` in the worker; fakes in tests). + * @returns resolves after the done message is posted (the tests await it; + * the real entry lets the worker exit naturally). + */ +export async function runWorkerMain( + port: BootstrapPort, + data: WorkerBootData, + streams: { stdout: PatchableStream; stderr: PatchableStream }, +): Promise { + const logs = new LogBuffer(data.maxLogBytes, (entry) => { port.postMessage({ type: 'log', entry }) }) + captureStreamWrites(logs, streams.stdout, 'stdout') + captureStreamWrites(logs, streams.stderr, 'stderr') + + const pending = new Map() + wireReplies(port, pending) + + const nextId = { value: 1 } + const namespaces = makeNamespaces(data, port, pending, nextId) + const consoleShim = makeConsoleShim(logs) + + let done: DoneMessage + try { + // The async function constructor, reached through an instance because + // `AsyncFunction` is not a global. The program body is strict-mode. + /* v8 ignore next -- the arrow exists only to reach the AsyncFunction constructor; it is never invoked. */ + const AsyncFunction = (async () => {}).constructor as new (...args: string[]) => (...fnArgs: unknown[]) => Promise + const fn = new AsyncFunction(...data.namespaces.map(namespace => namespace.global), 'console', `'use strict';\n${data.code}`) + const value = await fn(...namespaces, consoleShim) + done = { type: 'done', ...prepareValue(value, data.maxValueBytes) } + } catch (error: unknown) { + const message = error instanceof Error ? error.stack ?? error.message : String(error) + done = { type: 'done', error: { message } } + } + port.postMessage(done) +} diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts new file mode 100644 index 0000000000..dbd0a44966 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/src/index.ts @@ -0,0 +1,350 @@ +/** + * Worker-thread implementation of the code-execution seam: one fresh Node + * worker per run, executing the model's TypeScript after a host-side + * type-strip, with bindings bridged over the message port. Containment, not + * a security boundary (bash-equivalent trust — see the Code Mode RFC's + * trust-posture section): the worker gets an EMPTY environment, a heap cap, + * and two independent budgets — `computeMs` metered on the worker's + * measured event-loop busy time (a hot loop cannot hide behind a pending + * binding call) and a never-pausing `maxWallMs` ceiling — all funneling + * into `worker.terminate()`, which ends hot synchronous loops too. + * + * @module @deepseek-ai/dsh-code-runtime-worker + */ + +import { Worker } from 'node:worker_threads' +import { stripTypeScriptTypes } from 'node:module' +import { Context } from 'cordis' +import z from 'schemastery' +import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime' +import type { CodeBindingFunction, CodeLogEntry, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime' +import type { ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' + +export type { BootstrapPort, PatchableStream } from './bootstrap.ts' +export type { CallMessage, DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' + +/** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */ +export interface Config { + /** + * Busy-time budget in milliseconds: the run fails with kind `'timeout'` + * once the worker's MEASURED event-loop active time + * (`worker.performance.eventLoopUtilization()`) exceeds this. Metering + * measured busy time — not wall time, not host-side pending-call + * bookkeeping — is what makes the budget both fair (a program awaiting a + * slow tool accrues nothing) and ungameable (a hot loop accrues whether + * or not a decoy dispatch is in flight). + */ + computeMs?: number + /** + * Wall-clock ceiling in milliseconds; never pauses for anything. The + * backstop for what busy-time cannot see (a program awaiting a promise + * nobody will resolve). + */ + maxWallMs?: number + /** Shared byte budget for captured log text (console + raw stream writes), truncation marked in-band. */ + maxLogBytes?: number + /** Byte cap for the rendered completion value; an oversized or non-cloneable value crosses as a capped string rendering. */ + maxValueBytes?: number + /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */ + maxOldGenerationSizeMb?: number +} + +/** {@link Config} after schemastery fills the defaults (every field present). */ +type ResolvedConfig = Required + +/** + * How often the host samples the worker's event-loop utilization for the + * `computeMs` budget. An internal cadence, not config: the only effect of + * the interval is budget-expiry granularity (a run can overshoot by up to + * one interval), and nothing a deployment could tune here improves that + * without burning host CPU. + */ +const ELU_POLL_INTERVAL_MS = 25 + +/** ECMAScript reserved words that cannot be async-function parameter names — rejected as binding globals. */ +const RESERVED_WORDS = new Set([ + 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', + 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', + 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', + 'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package', + 'private', 'protected', 'public', 'arguments', 'eval', +]) + +/** Valid async-function parameter name (the binding global becomes one). */ +const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/ + +/** + * The shell a program is wrapped in for the type-strip, matching the + * grammatical context it will execute in (an async function body, where + * top-level `return` and `await` are legal — a bare module parse would + * reject the `return`). Strip mode is position-preserving (removed syntax + * becomes whitespace, nothing shifts), so the wrapper survives the strip + * byte-identical and the body slices back out with the model's own + * line/column positions intact. + */ +const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const + +/** One in-flight run's host-side state, tracked for disposal. */ +interface LiveRun { + worker: Worker + settle(failure: CodeRunFailure): void + finished: Promise +} + +/** + * The worker entry module. Source runs unbuilt (`src/worker.ts`, loadable + * directly on this repo's Node range via native type stripping — the file + * is erasable-only with type-only relative imports); the built package + * ships it as a sibling bundle (`lib/worker.js`, its own tsdown entry). + * The URL *pathname*'s extension says which world this module is in — + * pathname, because dev-time module runners (vitest) may suffix + * `import.meta.url` with a query string; relative resolution drops it. + */ +/* v8 ignore next -- the './worker.js' arm is the built-lib world, unreachable unbuilt by construction; the built-lib e2e pins it. */ +const WORKER_URL = new URL(new URL(import.meta.url).pathname.endsWith('.ts') ? './worker.ts' : './worker.js', import.meta.url) + +/** Render an unknown thrown value as a message, `Error` or not. */ +function messageOf(error: unknown): string { + return error instanceof Error ? error.message : String(error) +} + +/** + * The shipped {@link CodeRuntime} backend (`ctx.codeRuntime`). Registers as + * the `codeRuntime` service; every cap comes from validated config. See the + * module doc for the containment model and the class JSDoc on the seam for + * the contract this implements (error-as-field, hostile-peer port, + * no cross-run state, dispose to quiescence). + */ +export class WorkerCodeRuntime extends CodeRuntime { + static Config: z = z.object({ + computeMs: z.number().default(60_000), + maxWallMs: z.number().default(600_000), + maxLogBytes: z.number().default(65_536), + maxValueBytes: z.number().default(32_768), + maxOldGenerationSizeMb: z.number().default(512), + }) + + readonly language = 'typescript' + readonly isolation = 'worker-thread' + + private readonly config: ResolvedConfig + private readonly live = new Set() + private disposed = false + + constructor(ctx: Context, config: Config) { + super(ctx) + // Schemastery filled the defaults; the cast records that. Positivity is a + // semantic check the schema's plain number type does not carry. + this.config = config as ResolvedConfig + for (const [key, value] of Object.entries(this.config)) { + if (!(Number.isFinite(value) && value > 0)) throw new Error(`dsh-code-runtime-worker: config.${key} must be a positive number, got ${String(value)}`) + } + ctx.effect(() => () => this.teardown(), 'worker code-runtime teardown') + } + + /** + * Dispose to quiescence: mark the service unusable, fail every in-flight + * run as aborted, and AWAIT each worker's exit so no worker outlives the + * fiber. + */ + private async teardown(): Promise { + this.disposed = true + const runs = [...this.live] + for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' }) + await Promise.all(runs.map(run => run.finished)) + } + + /** + * Execute one program in a fresh worker. Program outcomes — including a + * type-strip syntax error, which never spawns a worker — resolve with + * `result.error`; the method rejects only for seam misuse (a disposed + * runtime, an invalid binding namespace). + * @param request - the program, its bindings, and the abort signal. + * @returns the run's outcome per the seam contract. + */ + async run(request: CodeRunRequest): Promise { + if (this.disposed) throw new Error('dsh-code-runtime-worker: run() after disposal') + const bindings = this.validateBindings(request) + if (request.signal?.aborted) { + return { logs: [], error: { kind: 'abort', message: String(request.signal.reason) } } + } + + let code: string + try { + const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + request.program + STRIP_WRAP.suffix) + code = stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length) + } catch (error: unknown) { + // A program that does not survive the type-strip (syntax error, + // non-erasable syntax like `enum`) is a program failure, reported the + // same way a thrown exception would be — and no worker ever spawns. + return { logs: [], error: { kind: 'exception', message: messageOf(error) } } + } + + return await this.execute(request, code, bindings) + } + + /** Reject (seam misuse) malformed binding namespaces: non-identifier or reserved globals, duplicates, and the `console` collision. */ + private validateBindings(request: CodeRunRequest): Map> { + const bindings = new Map>() + for (const namespace of request.bindings) { + if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) { + throw new Error(`dsh-code-runtime-worker: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`) + } + if (namespace.global === 'console' || bindings.has(namespace.global)) { + throw new Error(`dsh-code-runtime-worker: duplicate binding global ${JSON.stringify(namespace.global)}`) + } + bindings.set(namespace.global, namespace.functions) + } + return bindings + } + + /** Spawn the worker for one validated, type-stripped run and drive it to settlement. */ + private execute( + request: CodeRunRequest, + code: string, + bindings: Map>, + ): Promise { + const bootData: WorkerBootData = { + code, + namespaces: [...bindings].map(([global, functions]) => ({ global, names: Object.keys(functions) })), + maxLogBytes: this.config.maxLogBytes, + maxValueBytes: this.config.maxValueBytes, + } + const worker = new Worker(WORKER_URL, { + workerData: bootData, + // Model code gets NO ambient environment — stronger than the scrubbed + // env the defensive-patterns rule requires for spawned commands. + env: {}, + // Hermetic flags too: without this the worker inherits the host + // process's execArgv (a test runner's or tsx's loader hooks), which a + // bare isolate with an empty environment cannot satisfy. The entry + // needs nothing beyond native type stripping, on this repo's whole + // Node range. + execArgv: [], + resourceLimits: { maxOldGenerationSizeMb: this.config.maxOldGenerationSizeMb }, + // Backstop capture: the bootstrap patches JS-level writes into its own + // ordered buffer, so these pipes normally stay silent; anything that + // still arrives (native-level writes) is appended after the done logs. + stdout: true, + stderr: true, + }) + + return new Promise((resolve) => { + let settled = false + const answered = new Set() + const logs: CodeLogEntry[] = [] + const strayLogs: CodeLogEntry[] = [] + let strayBudget = this.config.maxLogBytes + + const captureStray = (source: 'stdout' | 'stderr') => (chunk: Buffer) => { + if (settled || strayBudget <= 0) return + const text = chunk.toString('utf8').slice(0, strayBudget) + strayBudget -= Buffer.byteLength(text, 'utf8') + strayLogs.push({ source, text }) + } + worker.stdout.on('data', captureStray('stdout')) + worker.stderr.on('data', captureStray('stderr')) + + // Settlement: exactly one outcome wins; every path funnels through + // here, cleans up the timers/listeners, terminates the worker, and + // resolves only after the worker actually exited (quiescence). Logs + // streamed eagerly before the settlement are kept — a timed-out or + // killed program still shows the model what it printed. + let finishResolve!: () => void + const finished = new Promise((done) => { finishResolve = done }) + const finish = (result: Omit): void => { + if (settled) return + settled = true + clearInterval(eluTimer) + clearTimeout(wallTimer) + request.signal?.removeEventListener('abort', onAbort) + this.live.delete(live) + void worker.terminate().then(() => { + finishResolve() + resolve({ ...result, logs: [...logs, ...strayLogs] }) + }) + } + + const onDone = (message: WorkerToHost): void => { + if (message.type !== 'done') return + finish({ + ...message.value !== undefined ? { value: message.value } : {}, + ...message.error ? { error: { kind: 'exception' as const, message: message.error.message } } : {}, + }) + } + + const onCall = (message: WorkerToHost): void => { + if (message.type !== 'call' || settled) return + // Hostile-peer rules: a duplicate id is ignored, an unknown name is + // answered with a failure, and a binding throw/reject becomes the + // program-side rejection — contained here, never a host crash. + if (answered.has(message.id)) return + answered.add(message.id) + const reply = (payload: ReplyMessage): void => { + if (settled) return + try { + worker.postMessage(payload) + } catch { + // The reply value failed structured clone; renegotiate as an error + // reply, which is always clone-plain. Nothing else throws here. + worker.postMessage({ type: 'reply', id: message.id, ok: false, message: 'binding resolution is not structured-cloneable' }) + } + } + const record = bindings.get(message.global) + // Own-property lookup only: a forged name like 'constructor' or + // 'hasOwnProperty' must not walk the record's prototype chain and + // reach a callable the consumer never declared. + const fn = record && Object.hasOwn(record, message.name) ? record[message.name] : undefined + if (typeof fn !== 'function') { + reply({ type: 'reply', id: message.id, ok: false, message: `unknown binding ${JSON.stringify(`${message.global}.${message.name}`)}` }) + return + } + void (async () => { + try { + reply({ type: 'reply', id: message.id, ok: true, value: await fn(message.args) }) + } catch (error: unknown) { + reply({ type: 'reply', id: message.id, ok: false, message: messageOf(error) }) + } + })() + } + + worker.on('message', (message: WorkerToHost) => { + if (message.type === 'log' && !settled) logs.push(message.entry) + onCall(message) + onDone(message) + }) + worker.on('error', (error: Error) => { + finish({ error: { kind: 'worker-exit', message: `worker error: ${error.message}` } }) + }) + worker.on('exit', (exitCode: number) => { + finish({ error: { kind: 'worker-exit', message: `worker exited with code ${exitCode} before completing` } }) + }) + + // The compute budget reads the worker's own measured busy time, so a + // hot loop expires it no matter what dispatches are in flight, while a + // program idling on a slow binding accrues nothing. + const eluTimer = setInterval(() => { + const elu = worker.performance.eventLoopUtilization() + if (elu.active > this.config.computeMs) { + finish({ error: { kind: 'timeout', message: `compute budget exhausted (${this.config.computeMs}ms busy)` } }) + } + }, ELU_POLL_INTERVAL_MS) + const wallTimer = setTimeout(() => { + finish({ error: { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` } }) + }, this.config.maxWallMs) + const onAbort = (): void => { + finish({ error: { kind: 'abort', message: String(request.signal?.reason) } }) + } + request.signal?.addEventListener('abort', onAbort, { once: true }) + + const live: LiveRun = { + worker, + finished, + settle: (failure: CodeRunFailure) => { finish({ error: failure }) }, + } + this.live.add(live) + }) + } +} + +export default WorkerCodeRuntime diff --git a/packages/code-runtime/code-runtime-worker/src/protocol.ts b/packages/code-runtime/code-runtime-worker/src/protocol.ts new file mode 100644 index 0000000000..85d5113b82 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/src/protocol.ts @@ -0,0 +1,65 @@ +/** + * Wire protocol between the host runtime and the worker bootstrap. Everything + * crossing the message port is structured-clone-plain and versionless — both + * ends ship in this package, always at the same version. The host treats + * inbound traffic as HOSTILE (the worker runs model code, which can reach + * `parentPort` via `import('node:worker_threads')` and forge any of these + * shapes); the worker treats inbound traffic as trusted. + * + * @module @deepseek-ai/dsh-code-runtime-worker/src/protocol + */ + +import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime' + +/** What the host hands the worker at spawn, via `workerData`. */ +export interface WorkerBootData { + /** The type-stripped (plain JS) program body. */ + code: string + /** Binding namespaces to materialize: the global name plus the function names (functions themselves stay host-side). */ + namespaces: { global: string; names: string[] }[] + /** Shared byte budget for captured log text; exceeding it drops further entries after one in-band marker. */ + maxLogBytes: number + /** Byte cap for the rendered completion value (see the value-preparation contract in bootstrap.ts). */ + maxValueBytes: number +} + +/** Worker → host: one bridged binding call. */ +export interface CallMessage { + type: 'call' + /** Worker-issued correlation id; the host answers each id at most once and ignores duplicates. */ + id: number + /** The namespace global the call targets. */ + global: string + /** The function name within the namespace. */ + name: string + /** The single argument, structured-clone-plain. */ + args: unknown +} + +/** Worker → host: one captured log entry, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */ +export interface LogMessage { + type: 'log' + entry: CodeLogEntry +} + +/** + * Worker → host: the program settled. `error` carries a program exception + * (the only failure the bootstrap itself can report — budgets, aborts, and + * substrate death are observed host-side). `value` is present only on a + * clean completion that produced one (already size-capped and + * clone-safe per the bootstrap's value preparation). Logs are NOT carried + * here — they streamed eagerly as {@link LogMessage}s. + */ +export interface DoneMessage { + type: 'done' + value?: unknown + error?: { message: string } +} + +/** Every message the worker sends. */ +export type WorkerToHost = CallMessage | LogMessage | DoneMessage + +/** Host → worker: the answer to one {@link CallMessage}. */ +export type ReplyMessage = + | { type: 'reply'; id: number; ok: true; value: unknown } + | { type: 'reply'; id: number; ok: false; message: string } diff --git a/packages/code-runtime/code-runtime-worker/src/worker.ts b/packages/code-runtime/code-runtime-worker/src/worker.ts new file mode 100644 index 0000000000..efaafdb038 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/src/worker.ts @@ -0,0 +1,20 @@ +/** + * The worker-thread entrypoint: self-executing glue over + * `bootstrap.ts`'s {@link runWorkerMain}, kept to the spawn wiring alone. + * Like `bin.ts` CLI entrypoints, this file executes only inside a spawned + * worker isolate — a place the coverage provider cannot observe — so it is + * excluded from the coverage gate while every line of actual logic lives in + * `bootstrap.ts`, unit-tested in-process; the real spawn path is pinned by + * the integration tests that run genuine workers. + * + * @module @deepseek-ai/dsh-code-runtime-worker/src/worker + */ + +import { parentPort, workerData } from 'node:worker_threads' +import { runWorkerMain } from './bootstrap.ts' +import type { WorkerBootData } from './protocol.ts' + +// A worker always has a parent port; guard loudly rather than run detached. +if (!parentPort) throw new Error('dsh-code-runtime-worker: worker entry loaded outside a worker thread') + +await runWorkerMain(parentPort, workerData as WorkerBootData, { stdout: process.stdout, stderr: process.stderr }) diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts new file mode 100644 index 0000000000..c4e5393634 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts @@ -0,0 +1,214 @@ +import { describe, expect, it } from 'vitest' +import { EventEmitter } from 'node:events' +import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, wireReplies } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts' +import type { BootstrapPort, PatchableStream, PendingCall } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts' +import type { ReplyMessage, WorkerToHost } from '@deepseek-ai/dsh-code-runtime-worker/src/protocol.ts' +import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime' + +/** + * An in-process stand-in for the worker's parentPort: the test plays the + * HOST side — inspect what the bootstrap posted, feed replies back — so + * every line of worker-side logic runs under coverage without spawning an + * isolate (real-worker behavior is pinned by runtime.spec.ts). + */ +class FakePort implements BootstrapPort { + sent: WorkerToHost[] = [] + private readonly emitter = new EventEmitter() + /** Host-scripted responder; return undefined to leave the call pending. */ + respond: (message: WorkerToHost) => ReplyMessage | undefined = () => undefined + + postMessage(message: WorkerToHost): void { + this.sent.push(message) + const reply = this.respond(message) + if (reply) queueMicrotask(() => this.emitter.emit('message', reply)) + } + + on(event: 'message', listener: (message: ReplyMessage) => void): void { + this.emitter.on(event, listener) + } + + deliver(message: ReplyMessage): void { + this.emitter.emit('message', message) + } + + logs(): CodeLogEntry[] { + return this.sent.filter(message => message.type === 'log').map(message => message.entry) + } + + done(): WorkerToHost | undefined { + return this.sent.find(message => message.type === 'done') + } +} + +function fakeStreams(): { stdout: PatchableStream; stderr: PatchableStream } { + return { stdout: { write: () => true }, stderr: { write: () => true } } +} + +const BOOT = { maxLogBytes: 65_536, maxValueBytes: 32_768 } + +describe('LogBuffer', () => { + it('streams entries to the sink until the byte budget, then emits one marker and drops the rest', () => { + const seen: CodeLogEntry[] = [] + const buffer = new LogBuffer(10, entry => seen.push(entry)) + buffer.push({ source: 'console', level: 'log', text: '12345' }) + buffer.push({ source: 'console', level: 'log', text: '123456' }) + buffer.push({ source: 'console', level: 'log', text: 'dropped' }) + expect(seen.map(entry => entry.text)).toEqual([ + '12345', + '[dsh-code-runtime-worker] log capture truncated at 10 bytes', + ]) + }) +}) + +describe('makeConsoleShim', () => { + it('captures the five levels and renders non-strings inspect-style', () => { + const seen: CodeLogEntry[] = [] + const shim = makeConsoleShim(new LogBuffer(1_000, entry => seen.push(entry))) + shim.log('plain', { a: 1 }) + shim.info('i') + shim.warn('w') + shim.error('e') + shim.debug('d') + expect(seen.map(entry => entry.level)).toEqual(['log', 'info', 'warn', 'error', 'debug']) + expect(seen[0]?.text).toBe('plain { a: 1 }') + expect(seen.every(entry => entry.source === 'console')).toBe(true) + }) +}) + +describe('captureStreamWrites', () => { + it('redirects writes into the buffer and restores on request', () => { + const seen: CodeLogEntry[] = [] + const buffer = new LogBuffer(1_000, entry => seen.push(entry)) + let underlying = '' + const stream: PatchableStream = { write: (chunk: unknown) => { underlying += String(chunk); return true } } + const restore = captureStreamWrites(buffer, stream, 'stdout') + stream.write('captured', 'utf8') + stream.write(Buffer.from('bytes')) + restore() + stream.write('after') + expect(seen.map(entry => entry.text)).toEqual(['captured', 'bytes']) + expect(seen[0]).toMatchObject({ source: 'stdout' }) + expect(underlying).toBe('after') + }) +}) + +describe('prepareValue', () => { + it('omits undefined, passes small cloneable values raw', () => { + expect(prepareValue(undefined, 100)).toEqual({}) + expect(prepareValue({ a: [1, 'two'] }, 100)).toEqual({ value: { a: [1, 'two'] } }) + }) + + it('replaces a non-cloneable value with its rendering', () => { + const { value } = prepareValue({ fn: () => 1 }, 1_000) + expect(typeof value).toBe('string') + expect(value).toContain('fn') + }) + + it('replaces an oversized value with a truncation-marked capped rendering', () => { + const { value } = prepareValue('x'.repeat(50), 10) + expect(value).toBe(`${'x'.repeat(10)}… [truncated]`) + }) +}) + +describe('makeNamespaces', () => { + it('exposes prototype-colliding names as ordinary own properties', async () => { + const port = new FakePort() + port.respond = message => message.type === 'call' ? { type: 'reply', id: message.id, ok: true, value: `${message.name}-ok` } : undefined + const pending = new Map() + wireReplies(port, pending) + const [tools] = makeNamespaces({ namespaces: [{ global: 'tools', names: ['__proto__', 'constructor', 'toString'] }] }, port, pending, { value: 1 }) as [Record Promise>] + expect(Object.getPrototypeOf(tools)).toBeNull() + await expect(tools['__proto__']?.({})).resolves.toBe('__proto__-ok') + await expect(tools['constructor']?.({})).resolves.toBe('constructor-ok') + await expect(tools['toString']?.({})).resolves.toBe('toString-ok') + }) + + it('rejects a non-cloneable argument without leaking the pending entry', async () => { + let firstCall = true + const throwingPort: BootstrapPort = { + // First call throws an Error (the real DataCloneError shape), the + // second a bare string — the rejection renders both. + postMessage: () => { + if (firstCall) { firstCall = false; throw new Error('DataCloneError-ish') } + throw 'raw-clone-failure' + }, + on: () => {}, + } + const pending = new Map() + const [tools] = makeNamespaces({ namespaces: [{ global: 'tools', names: ['x'] }] }, throwingPort, pending, { value: 1 }) as [Record Promise>] + await expect(tools.x?.(() => 1)).rejects.toThrow(/structured-cloneable: DataCloneError-ish/) + await expect(tools.x?.(() => 1)).rejects.toThrow(/structured-cloneable: raw-clone-failure/) + expect(pending.size).toBe(0) + }) +}) + +describe('runWorkerMain', () => { + it('runs a program end-to-end: bindings, console, return value', async () => { + const port = new FakePort() + port.respond = message => message.type === 'call' ? { type: 'reply', id: message.id, ok: true, value: (message.args as { n: number }).n * 2 } : undefined + await runWorkerMain(port, { + ...BOOT, + code: 'const doubled = await tools.double({ n: 21 }); console.log("got", doubled); return { doubled };', + namespaces: [{ global: 'tools', names: ['double'] }], + }, fakeStreams()) + expect(port.logs()).toEqual([{ source: 'console', level: 'log', text: 'got 42' }]) + expect(port.done()).toEqual({ type: 'done', value: { doubled: 42 } }) + }) + + it('reports a thrown program error on the done message', async () => { + const port = new FakePort() + await runWorkerMain(port, { ...BOOT, code: 'throw new Error("boom")', namespaces: [] }, fakeStreams()) + const done = port.done() + expect(done?.type).toBe('done') + expect(done?.type === 'done' ? done.error?.message : undefined).toContain('boom') + expect(done?.type === 'done' ? done.value : undefined).toBeUndefined() + }) + + it('renders non-Error throws and stack-less Errors on the done message', async () => { + const rawPort = new FakePort() + await runWorkerMain(rawPort, { ...BOOT, code: 'throw "raw-throw"', namespaces: [] }, fakeStreams()) + expect(rawPort.done()).toEqual({ type: 'done', error: { message: 'raw-throw' } }) + + const barePort = new FakePort() + await runWorkerMain(barePort, { ...BOOT, code: 'const e = new Error("bare"); e.stack = undefined; throw e', namespaces: [] }, fakeStreams()) + expect(barePort.done()).toEqual({ type: 'done', error: { message: 'bare' } }) + }) + + it('surfaces a host failure reply as a program-side rejection it can catch', async () => { + const port = new FakePort() + port.respond = message => message.type === 'call' ? { type: 'reply', id: message.id, ok: false, message: 'denied by host' } : undefined + await runWorkerMain(port, { + ...BOOT, + code: 'try { await tools.x({}) } catch (error) { return `caught: ${error.message}` }', + namespaces: [{ global: 'tools', names: ['x'] }], + }, fakeStreams()) + expect(port.done()).toEqual({ type: 'done', value: 'caught: denied by host' }) + }) + + it('ignores replies for unknown pending ids', async () => { + const port = new FakePort() + port.respond = (message) => { + if (message.type !== 'call') return undefined + // Deliver a stray reply first; the real one follows. + port.deliver({ type: 'reply', id: 9_999, ok: true, value: 'stray' }) + return { type: 'reply', id: message.id, ok: true, value: 'real' } + } + await runWorkerMain(port, { + ...BOOT, + code: 'return await tools.x({})', + namespaces: [{ global: 'tools', names: ['x'] }], + }, fakeStreams()) + expect(port.done()).toEqual({ type: 'done', value: 'real' }) + }) + + it('captures raw stream writes through the patched process streams', async () => { + const port = new FakePort() + const streams = fakeStreams() + await runWorkerMain(port, { ...BOOT, code: 'return 1', namespaces: [] }, streams) + streams.stdout.write('never seen — already restored? no: patch persists in worker') + // The patch stays installed for the worker's lifetime; writes during the + // program landed in order. Here the program wrote nothing via streams, so + // only the post-run write above went through the patched slot. + expect(port.logs().at(-1)).toMatchObject({ source: 'stdout' }) + }) +}) diff --git a/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts b/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts new file mode 100644 index 0000000000..66ce1830b6 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts @@ -0,0 +1,55 @@ +import { spawn } from 'node:child_process' +import { existsSync } from 'node:fs' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { describe, expect, it } from 'vitest' + +/** + * BUILT-ARTIFACT smoke for the published package (the real-load-path guard + * from docs/testing.md): the unit suite runs `src/` under vitest, where the + * worker entry resolves to `src/worker.ts` — a consumer runs `lib/index.js` + * under plain `node`, where it must resolve the sibling `lib/worker.js` + * bundle instead. This spawns plain `node` (NOT tsx) from inside the package + * directory and imports the package BY NAME, so resolution flows through the + * real `exports` map exactly as it would from a downstream install; the + * program exercises the type-strip, the worker spawn, the binding bridge, + * and log capture end-to-end through the built bundles. + * + * It build-gates: SKIPS when the built artifacts are absent (suite run + * without `pnpm run build`); CI runs it after the build step. KEYLESS — no + * model is involved. + */ + +const pkgDir = fileURLToPath(new URL('..', import.meta.url)) +const built = ['lib/index.js', 'lib/worker.js'].every(file => existsSync(join(pkgDir, file))) + && existsSync(join(pkgDir, '../code-runtime/lib/index.js')) + +describe.skipIf(!built)('built lib real load path (plain node)', () => { + it('runs a TypeScript program with a binding through lib/index.js and its lib/worker.js entry', async () => { + const script = ` + const { Context } = await import('cordis') + const { WorkerCodeRuntime } = await import('@deepseek-ai/dsh-code-runtime-worker') + const ctx = new Context() + await ctx.plugin(WorkerCodeRuntime, {}) + const result = await ctx.codeRuntime.run({ + program: 'const doubled: number = await tools.double({ n: 21 }); console.log("halfway", doubled); return doubled;', + bindings: [{ global: 'tools', functions: { double: async args => args.n * 2 } }], + }) + console.log(JSON.stringify(result)) + process.exit(0) + ` + const child = spawn(process.execPath, ['--input-type=module', '-e', script], { cwd: pkgDir, stdio: ['ignore', 'pipe', 'pipe'] }) + let stdout = '' + let stderr = '' + child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8') }) + child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') }) + const exitCode = await new Promise(resolve => child.on('close', resolve)) + + expect(exitCode, `stderr:\n${stderr}`).toBe(0) + const lastLine = stdout.trim().split('\n').at(-1) ?? '' + const result = JSON.parse(lastLine) as { value?: unknown; logs: { source: string; level?: string; text: string }[]; error?: unknown } + expect(result.error).toBeUndefined() + expect(result.value).toBe(42) + expect(result.logs).toContainEqual({ source: 'console', level: 'log', text: 'halfway 42' }) + }) +}) diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts new file mode 100644 index 0000000000..8edfdc6a41 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts @@ -0,0 +1,328 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker' +import type { Config } from '@deepseek-ai/dsh-code-runtime-worker' +import type { CodeRunResult } from '@deepseek-ai/dsh-code-runtime' + +/** + * Integration suite over REAL worker threads (no mocks — workers are cheap + * and local, per docs/testing.md's real-over-mock policy). Each test builds + * a fresh context so budgets can be tuned per case. + */ +async function setup(config: Config = {}) { + const ctx = new Context() + await ctx.plugin(WorkerCodeRuntime, config) + const runtime = ctx.codeRuntime as WorkerCodeRuntime + return { ctx, runtime } +} + +/** Convenience: one namespace `tools` with the given functions. */ +function tools(functions: Record Promise>) { + return [{ global: 'tools', functions }] +} + +describe('WorkerCodeRuntime — programs and bindings (real workers)', () => { + it('registers with the seam descriptors', async () => { + const { runtime } = await setup() + expect(runtime.language).toBe('typescript') + expect(runtime.isolation).toBe('worker-thread') + }) + + it('runs TypeScript (erasable syntax), captures console/stdout in order, returns the value', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: ` + interface Point { x: number; y: number } + const p: Point = { x: 1, y: 2 } as Point; + console.log('point', p); + process.stdout.write('raw-out\\n'); + console.warn('careful'); + return p.x + p.y; + `, + bindings: [], + }) + expect(result.error).toBeUndefined() + expect(result.value).toBe(3) + expect(result.logs.map(entry => [entry.source, entry.level ?? null])).toEqual([ + ['console', 'log'], + ['stdout', null], + ['console', 'warn'], + ]) + expect(result.logs[0]?.text).toBe('point { x: 1, y: 2 }') + }) + + it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => { + const { runtime } = await setup() + const calls: unknown[] = [] + const result = await runtime.run({ + program: ` + const first = await tools.echo({ n: 1 }); + let caught = ''; + try { await tools.fail({}) } catch (error) { caught = error.message } + let caughtRaw = ''; + try { await tools.failRaw({}) } catch (error) { caughtRaw = error.message } + return { first, caught, caughtRaw }; + `, + bindings: tools({ + echo: async (args) => { calls.push(args); return { echoed: args } }, + fail: async () => { throw new Error('nope') }, + // A non-Error throw: the host renders it, the program still catches. + failRaw: async () => { throw 'raw-nope' }, + }), + }) + expect(result.error).toBeUndefined() + expect(result.value).toEqual({ first: { echoed: { n: 1 } }, caught: 'nope', caughtRaw: 'raw-nope' }) + expect(calls).toEqual([{ n: 1 }]) + }) + + it('reports non-erasable syntax as an exception without spawning a worker', async () => { + const { runtime } = await setup() + const result = await runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] }) + expect(result.error?.kind).toBe('exception') + expect(result.error?.message).toMatch(/enum|strip/i) + }) + + it('reports a runtime throw as an exception with the message', async () => { + const { runtime } = await setup() + const result = await runtime.run({ program: 'throw new Error("kaboom")', bindings: [] }) + expect(result.error?.kind).toBe('exception') + expect(result.error?.message).toContain('kaboom') + }) + + it('gives the program an EMPTY environment', async () => { + const { runtime } = await setup() + const result = await runtime.run({ program: 'return JSON.stringify(process.env)', bindings: [] }) + expect(result.value).toBe('{}') + }) + + it('replaces a non-cloneable return value with a string rendering', async () => { + const { runtime } = await setup() + const result = await runtime.run({ program: 'return { f: () => 1 }', bindings: [] }) + expect(typeof result.value).toBe('string') + }) + + it('keeps logs streamed before a failure', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: 'console.log("before"); throw new Error("after-log")', + bindings: [], + }) + expect(result.error?.kind).toBe('exception') + expect(result.logs.map(entry => entry.text)).toContain('before') + }) +}) + +describe('WorkerCodeRuntime — budgets and containment (real workers)', () => { + it('ends a hot loop at the compute budget — including behind a pending decoy dispatch', async () => { + const { runtime } = await setup({ computeMs: 300, maxWallMs: 30_000 }) + const result = await runtime.run({ + // The decoy: fire a call at a never-resolving binding WITHOUT awaiting, + // then spin. Host-side pending-call bookkeeping would pause a naive + // budget here; measured busy time cannot be fooled. + program: 'void tools.slow({}); for (;;) {}', + bindings: tools({ slow: () => new Promise(() => {}) }), + }) + expect(result.error?.kind).toBe('timeout') + expect(result.error?.message).toContain('compute budget') + }, 15_000) + + it('does not charge time spent awaiting a slow binding against the compute budget', async () => { + const { runtime } = await setup({ computeMs: 250, maxWallMs: 30_000 }) + const result = await runtime.run({ + program: 'return await tools.slow({})', + bindings: tools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 700)) }), + }) + expect(result.error).toBeUndefined() + expect(result.value).toBe('slow-done') + }, 15_000) + + it('ends an idle-forever run at the wall-clock ceiling', async () => { + const { runtime } = await setup({ computeMs: 30_000, maxWallMs: 400 }) + const result = await runtime.run({ + program: 'await tools.never({}); return 1', + bindings: tools({ never: () => new Promise(() => {}) }), + }) + expect(result.error?.kind).toBe('timeout') + expect(result.error?.message).toContain('wall-clock ceiling') + }, 15_000) + + it('reports an abort mid-run and stops the worker', async () => { + const { runtime } = await setup() + const controller = new AbortController() + setTimeout(() => { controller.abort('user-cancel') }, 150) + const result = await runtime.run({ program: 'for (;;) {}', bindings: [], signal: controller.signal }) + expect(result.error).toEqual({ kind: 'abort', message: 'user-cancel' }) + }, 15_000) + + it('reports a pre-aborted signal without spawning', async () => { + const { runtime } = await setup() + const controller = new AbortController() + controller.abort('too-late') + const result = await runtime.run({ program: 'return 1', bindings: [], signal: controller.signal }) + expect(result.error).toEqual({ kind: 'abort', message: 'too-late' }) + }) + + it('drops a binding resolution that lands after the run settled', async () => { + const { runtime } = await setup() + const controller = new AbortController() + let replyDelivered!: Promise + const result = await runtime.run({ + program: 'void tools.late({}); for (;;) {}', + bindings: tools({ + // Anchored on invocation: abort 100ms after the call reaches the + // host, resolve 400ms after — by then the run has settled, so the + // resolution's reply hits the post-settlement drop. + late: () => new Promise((resolve) => { + setTimeout(() => { controller.abort('cancel-now') }, 100) + replyDelivered = new Promise(done => setTimeout(() => { resolve('too-late'); done() }, 400)) + }), + }), + signal: controller.signal, + }) + expect(result.error).toEqual({ kind: 'abort', message: 'cancel-now' }) + // Let the late resolution actually fire so its reply executes instead of + // being cancelled with the test. + await replyDelivered + }, 15_000) + + it('contains an OOM under resourceLimits as worker-exit, host process healthy', async () => { + const { runtime } = await setup({ maxOldGenerationSizeMb: 32 }) + const result = await runtime.run({ + program: 'const hog = []; for (;;) hog.push(new Array(1e6).fill(1));', + bindings: [], + }) + expect(result.error?.kind).toBe('worker-exit') + // And the host is fine: run something else. + const after = await runtime.run({ program: 'return "alive"', bindings: [] }) + expect(after.value).toBe('alive') + }, 30_000) + + it('truncates runaway log output at the byte budget with an in-band marker', async () => { + const { runtime } = await setup({ maxLogBytes: 300 }) + const result = await runtime.run({ + program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1', + bindings: [], + }) + expect(result.logs.at(-1)?.text).toContain('truncated at 300 bytes') + const total = result.logs.reduce((sum, entry) => sum + Buffer.byteLength(entry.text, 'utf8'), 0) + expect(total).toBeLessThan(1_000) + }) + + it('caps an oversized return value with a truncation marker', async () => { + const { runtime } = await setup({ maxValueBytes: 64 }) + const result = await runtime.run({ program: 'return "y".repeat(10_000)', bindings: [] }) + expect(result.value).toBe(`${'y'.repeat(64)}… [truncated]`) + }) + + it('captures pipe writes that bypass the patched write slot as stray logs, capped by the same budget', async () => { + const { runtime } = await setup({ maxLogBytes: 4 }) + const result = await runtime.run({ + // The bootstrap patches the stream instance's own `write`; going + // through the prototype's slot reaches the real pipe underneath, so + // the bytes arrive host-side as stray data. The pauses keep the two + // writes in separate pipe chunks and let them land before settlement. + program: ` + const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text); + write('abcd'); + await new Promise(resolve => setTimeout(resolve, 150)); + write('ef'); + await new Promise(resolve => setTimeout(resolve, 100)); + return 1; + `, + bindings: [], + }) + expect(result.error).toBeUndefined() + expect(result.logs).toContainEqual({ source: 'stdout', text: 'abcd' }) + expect(result.logs.map(entry => entry.text)).not.toContain('ef') + }, 15_000) +}) + +describe('WorkerCodeRuntime — hostile programs (real workers)', () => { + it('survives forged port traffic: unknown binding names, duplicate ids, junk shapes', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: ` + const { parentPort } = await import('node:worker_threads'); + parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} }); + parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} }); + parentPort.postMessage({ type: 'call', id: 7778, global: 'tools', name: 'constructor', args: {} }); + parentPort.postMessage({ type: 'junk' }); + return await tools.real({}); + `, + bindings: tools({ real: async () => 'still-works' }), + }) + expect(result.error).toBeUndefined() + expect(result.value).toBe('still-works') + }) + + it('answers a binding whose resolution cannot be cloned with a failure reply', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: 'try { await tools.bad({}) } catch (error) { return error.message }', + bindings: tools({ bad: async () => (() => 1) }), + }) + expect(result.value).toContain('not structured-cloneable') + }) + + it('exposes binding names that collide with Object.prototype as ordinary functions', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: 'return [await tools["__proto__"]({}), await tools["constructor"]({}), typeof tools["hasOwnProperty"]]', + // Computed keys: a literal `'__proto__': …` entry would SET the record's + // prototype instead of declaring a binding of that name. + bindings: tools({ ['__proto__']: async () => 'proto-ok', ['constructor']: async () => 'ctor-ok' }), + }) + expect(result.value).toEqual(['proto-ok', 'ctor-ok', 'undefined']) + }) +}) + +describe('WorkerCodeRuntime — seam misuse and lifecycle', () => { + it('rejects invalid binding globals loudly (identifier, reserved word, duplicate, console)', async () => { + const { runtime } = await setup() + const cases: [string, RegExp][] = [ + ['not valid!', /not a usable identifier/], + ['await', /not a usable identifier/], + ['console', /duplicate binding global/], + ] + for (const [global, message] of cases) { + await expect(runtime.run({ program: 'return 1', bindings: [{ global, functions: {} }] })).rejects.toThrow(message) + } + await expect(runtime.run({ + program: 'return 1', + bindings: [{ global: 'tools', functions: {} }, { global: 'tools', functions: {} }], + })).rejects.toThrow(/duplicate binding global/) + }) + + it('rejects config values that are not positive numbers', async () => { + const ctx = new Context() + await expect(ctx.plugin(WorkerCodeRuntime, { computeMs: -1 })).rejects.toThrow(/positive number/) + }) + + it('keeps runs isolated: no state survives from one run to the next', async () => { + const { runtime } = await setup() + await runtime.run({ program: 'globalThis.leak = "value"; return 1', bindings: [] }) + const second = await runtime.run({ program: 'return typeof globalThis.leak', bindings: [] }) + expect(second.value).toBe('undefined') + }) + + it('disposal aborts in-flight runs, awaits worker exit, and rejects later runs', async () => { + const ctx = new Context() + const fiber = await ctx.plugin(WorkerCodeRuntime) + const runtime = ctx.codeRuntime as WorkerCodeRuntime + const inflight: Promise = runtime.run({ program: 'for (;;) {}', bindings: [] }) + // Give the worker a moment to actually start spinning. + await new Promise(resolve => setTimeout(resolve, 200)) + await fiber.dispose() + const result = await inflight + expect(result.error).toEqual({ kind: 'abort', message: 'runtime disposed' }) + await expect(runtime.run({ program: 'return 1', bindings: [] })).rejects.toThrow(/after disposal/) + }, 15_000) + + it('removes ctx.codeRuntime when the providing fiber disposes (HMR safety)', async () => { + const ctx = new Context() + const fiber = await ctx.plugin(WorkerCodeRuntime) + expect(ctx.get('codeRuntime')).toBeInstanceOf(WorkerCodeRuntime) + await fiber.dispose() + expect(ctx.get('codeRuntime')).toBeUndefined() + }) +}) diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json new file mode 100644 index 0000000000..af962eda4f --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/tsconfig.json @@ -0,0 +1,24 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../code-runtime" + } + ] +} diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts new file mode 100644 index 0000000000..234ec4c6b9 --- /dev/null +++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts @@ -0,0 +1,18 @@ +import { defineConfig } from 'tsdown' + +/** + * Package-shape override (see the root tsdown.config.ts): besides the + * default lib/index.js bundle, the worker BOOTSTRAP ships as its own + * sibling entry — `new Worker(new URL('./worker.js', import.meta.url))` + * loads it as a file, so it cannot be part of the index bundle. + */ +export default defineConfig({ + entry: ['lib/types/index.js', 'lib/types/worker.js'], + outDir: 'lib', + format: ['esm'], + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: false, +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ccf2f6978d..03a47d6866 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -133,6 +133,19 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/code-runtime/code-runtime-worker: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-code-runtime': + specifier: workspace:^ + version: link:../code-runtime + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/compact/compact: devDependencies: '@deepseek-ai/dsh-llm': diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts index f579169ab0..4d7d0802c7 100644 --- a/scripts/check-workspace-constraints.ts +++ b/scripts/check-workspace-constraints.ts @@ -105,11 +105,26 @@ const dshBinPackageFiles = [ 'src', ] as const +// Packages that ship a worker-thread entry as a sibling runtime bundle +// (lib/worker.js, its own tsdown entry): the bootstrap is loaded via +// `new Worker(new URL('./worker.js', import.meta.url))`, so it cannot live +// inside the index bundle and must be published alongside it. +const workerEntryPackages = new Set(['@deepseek-ai/dsh-code-runtime-worker']) + +const dshWorkerPackageFiles = [ + 'lib/index.js', + 'lib/worker.js', + 'lib/types/**/*.d.ts', + 'lib/types/**/*.d.ts.map', + 'src', +] as const + function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean { return !!actual && actual.length === expected.length && actual.every((value, index) => value === expected[index]) } function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] { + if (manifest.name && workerEntryPackages.has(manifest.name)) return dshWorkerPackageFiles return manifest.bin ? dshBinPackageFiles : dshPackageFiles } diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 6440a672be..2848578f49 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -154,7 +154,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'code-runtime', title: 'Code-execution seam', mode: 'seam', - implementations: [], + implementations: ['code-runtime-worker'], consumers: [], note: 'Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer).', }, diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 6c844f842a..9ab71c6b61 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -310,6 +310,7 @@ function builtBinSmokeGate(): Gate { 'vitest.e2e.config.ts', 'packages/ui/stdio-agent/tests/built-bin.e2e.ts', 'packages/ui/acp-agent/tests/built-bin.e2e.ts', + 'packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts', ], { label: 'built-bin smoke', needs: ['build'], diff --git a/tsconfig.build.json b/tsconfig.build.json index 00739a361d..9040d83f2b 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -23,6 +23,7 @@ { "path": "./packages/core/agent-core" }, { "path": "./packages/bash/bash" }, { "path": "./packages/code-runtime/code-runtime" }, + { "path": "./packages/code-runtime/code-runtime-worker" }, { "path": "./packages/compact/compact" }, { "path": "./packages/compact/compact-basic" }, { "path": "./packages/llm/llm-deepseek" }, diff --git a/tsconfig.json b/tsconfig.json index 5d90943c1a..22b2a65a39 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -34,6 +34,7 @@ { "path": "./packages/core/agent-core" }, { "path": "./packages/bash/bash" }, { "path": "./packages/code-runtime/code-runtime" }, + { "path": "./packages/code-runtime/code-runtime-worker" }, { "path": "./packages/llm/llm-deepseek" }, { "path": "./packages/llm/llm-pi-ai" }, { "path": "./packages/bash/bash-local" }, diff --git a/vitest.config.ts b/vitest.config.ts index 4200b5c7f4..11d1454b08 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -31,7 +31,12 @@ export default defineConfig({ // can't import one without booting it, so they are driven by the keyless // Loader-path smoke (a real subprocess) instead of the in-process unit // suite — the same reason `examples/start.ts` sat out of coverage scope. - exclude: ['packages/*/*/src/types.ts', 'packages/*/*/src/bin.ts'], + // `worker.ts` files are the same class as bin.ts: self-executing + // worker-thread entrypoints that only ever run inside a spawned isolate + // the v8 provider cannot observe. They stay thin glue over in-process- + // tested logic (bootstrap.ts) and are pinned by real-worker integration + // tests. + exclude: ['packages/*/*/src/types.ts', 'packages/*/*/src/bin.ts', 'packages/*/*/src/worker.ts'], // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome). // Per-file so a well-covered big file can't subsidize a bare one. // Every v8 ignore comment must carry a reason — see the quality-gates RFC From aa2a7f9a8a03dfbad4b1d7e32c3af67fdbabd513 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:39:57 +0800 Subject: [PATCH 039/119] fix: validate and re-cap all inbound worker-port traffic (Codex round 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The host's message listener trusted the compile-time WorkerToHost shape on traffic from a peer that runs model code: postMessage(null) threw in the listener and crashed the host process; forged log/done messages bypassed maxLogBytes/maxValueBytes (the worker-side LogBuffer and prepareValue cap only honest flows); and the error-reply renegotiation re-echoed a forged non-cloneable call id, throwing outside any catch. Every inbound message now passes a runtime shape gate that validates and REBUILDS it field by field (junk drops without a throw; call ids must be numbers, so replies are always clone-plain; forged extra fields never ride along). One host-side ledger bounds everything landing in logs — honest port entries, forged ones, and stray pipe bytes — at the single documented maxLogBytes, with the shared in-band truncation marker emitted host-side when the ledger trips first; the completion value is re-capped host-side through the same prepareValue (with exactly the truncation suffix as slack so honest worker-capped values pass unchanged), and done error text is bounded. Also folds the stray-capture budget into that shared ledger (round-1 finding B: it was a second maxLogBytes on top of the documented shared cap). --- docs/config-catalog.md | 2 +- .../code-runtime-worker/README.md | 4 +- .../code-runtime-worker/src/bootstrap.ts | 3 +- .../code-runtime-worker/src/index.ts | 106 ++++++++++++++++-- .../code-runtime-worker/src/protocol.ts | 13 +++ .../code-runtime-worker/tests/runtime.spec.ts | 77 +++++++++++++ 6 files changed, 192 insertions(+), 13 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 6510aea849..6339911606 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -171,7 +171,7 @@ export interface Config { } ``` -Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:27`](../packages/code-runtime/code-runtime-worker/src/index.ts) +Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:29`](../packages/code-runtime/code-runtime-worker/src/index.ts) ## `@deepseek-ai/dsh-compact-basic` diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md index 13bf992bb5..b8f440397a 100644 --- a/packages/code-runtime/code-runtime-worker/README.md +++ b/packages/code-runtime/code-runtime-worker/README.md @@ -21,9 +21,9 @@ Every field is validated (positive numbers) and defaulted; there are no other tu - **One fresh worker per run, no pooling** — a program's world dies with its worker: no cross-run state to log, state bleed unrepresentable, runs reconstructable from the session log alone. - **Type-strip host-side, in execution context** — the program is wrapped in an async-function shell, stripped with `node:module`'s `stripTypeScriptTypes` (erasable syntax only — `enum`/namespaces are rejected as a program `exception` and no worker spawns), and sliced back out byte-positioned; it then executes as the body of an `AsyncFunction`, so top-level `await`/`return` work. -- **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and converts a non-cloneable binding resolution into an error reply. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys. +- **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so every inbound message is shape-validated and REBUILT before anything reads it (`null`, primitives, junk types, and malformed payloads drop without a throw; forged extra fields never ride along), the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and converts a non-cloneable binding resolution into an error reply. Forged `log`/`done` messages cannot bypass the caps: one host-side ledger bounds everything that lands in `logs`, and the completion value is re-capped host-side. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys. - **Two independent budgets, because the peer is hostile** — `computeMs` meters the worker's MEASURED busy time (`worker.performance.eventLoopUtilization()` polling): a hot loop cannot hide behind a pending decoy dispatch, and a program awaiting a slow tool accrues nothing. `maxWallMs` backstops what busy time cannot see (awaiting a promise nobody resolves). Both funnel into `worker.terminate()`, which ends hot synchronous loops too; heap overflow surfaces as the worker's OOM exit (`kind: 'worker-exit'`). -- **Logs stream eagerly** — console/stdout/stderr entries cross the port as they happen, so a timed-out or killed program still shows what it printed; pipe bytes that bypass the patched streams are appended after, under the same byte budget. +- **Logs stream eagerly** — console/stdout/stderr entries cross the port as they happen, so a timed-out or killed program still shows what it printed. ONE shared `maxLogBytes` ledger bounds everything: streamed entries, forged port traffic, and pipe bytes that bypass the patched streams (appended after), with the overflow marked in-band once. - **Empty environment** — the worker gets `env: {}` and `execArgv: []`: no ambient credentials (stronger than the scrubbed-env rule for spawned commands) and no inherited loader flags. - **Dispose to quiescence** — teardown fails in-flight runs as `abort` and AWAITS each worker's exit before resolving. diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts index 06cef02c7b..ae6bcf25bf 100644 --- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts +++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts @@ -12,6 +12,7 @@ import { inspect } from 'node:util' import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime' +import { logTruncationMarker } from './protocol.ts' import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' /** The port surface the bootstrap needs — satisfied by `parentPort` and by the tests' fake. */ @@ -62,7 +63,7 @@ export class LogBuffer { const cost = Buffer.byteLength(entry.text, 'utf8') if (cost > this.remaining) { this.truncated = true - this.sink({ source: 'stderr', text: `[dsh-code-runtime-worker] log capture truncated at ${this.maxBytes} bytes` }) + this.sink({ source: 'stderr', text: logTruncationMarker(this.maxBytes) }) return } this.remaining -= cost diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts index dbd0a44966..a2385ba83e 100644 --- a/packages/code-runtime/code-runtime-worker/src/index.ts +++ b/packages/code-runtime/code-runtime-worker/src/index.ts @@ -18,6 +18,8 @@ import { Context } from 'cordis' import z from 'schemastery' import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime' import type { CodeBindingFunction, CodeLogEntry, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime' +import { prepareValue } from './bootstrap.ts' +import { logTruncationMarker } from './protocol.ts' import type { ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' export type { BootstrapPort, PatchableStream } from './bootstrap.ts' @@ -108,6 +110,64 @@ function messageOf(error: unknown): string { return error instanceof Error ? error.message : String(error) } +/** The log sources / console levels the seam vocabulary admits, as runtime sets for inbound-message validation. */ +const LOG_SOURCES = new Set(['console', 'stdout', 'stderr']) +const LOG_LEVELS = new Set(['log', 'info', 'warn', 'error', 'debug']) + +/** + * Runtime shape gate for inbound port traffic. The peer runs MODEL CODE and + * can post anything — `null`, primitives, objects with poisoned fields — so + * the compile-time `WorkerToHost` type means nothing here: everything is + * re-validated and REBUILT field by field (a forged extra field never rides + * along; a non-number call id can never be echoed into a reply). Junk returns + * `undefined` and is dropped — a throw in the host's `message` listener would + * crash the host process. + */ +function parseWorkerMessage(raw: unknown): WorkerToHost | undefined { + if (typeof raw !== 'object' || raw === null) return undefined + const m = raw as Record + switch (m.type) { + case 'call': { + if (typeof m.id !== 'number' || typeof m.global !== 'string' || typeof m.name !== 'string') return undefined + return { type: 'call', id: m.id, global: m.global, name: m.name, args: m.args } + } + case 'log': { + const entry = m.entry + if (typeof entry !== 'object' || entry === null) return undefined + const e = entry as Record + if (typeof e.text !== 'string') return undefined + if (typeof e.source !== 'string' || !LOG_SOURCES.has(e.source)) return undefined + if (e.level !== undefined && (typeof e.level !== 'string' || !LOG_LEVELS.has(e.level))) return undefined + return { + type: 'log', + entry: { + source: e.source as CodeLogEntry['source'], + ...e.level !== undefined ? { level: e.level as Exclude } : {}, + text: e.text, + }, + } + } + case 'done': { + if (m.error === undefined) return { type: 'done', ...m.value !== undefined ? { value: m.value } : {} } + const error = m.error + if (typeof error !== 'object' || error === null) return undefined + const message = (error as Record).message + if (typeof message !== 'string') return undefined + return { type: 'done', ...m.value !== undefined ? { value: m.value } : {}, error: { message } } + } + default: return undefined + } +} + +/** + * Headroom the host's value re-cap grants over `maxValueBytes`: exactly the + * truncation suffix {@link prepareValue} appends, so a value the WORKER + * already capped passes through unchanged instead of being marked twice. + * (A multibyte rendering the worker sliced by characters can still exceed + * this and pick up a second marker — bounded and harmless.) + */ +const VALUE_RENDER_SLACK = Buffer.byteLength('… [truncated]', 'utf8') + /** * The shipped {@link CodeRuntime} backend (`ctx.codeRuntime`). Registers as * the `codeRuntime` service; every cap comes from validated config. See the @@ -234,13 +294,32 @@ export class WorkerCodeRuntime extends CodeRuntime { const answered = new Set() const logs: CodeLogEntry[] = [] const strayLogs: CodeLogEntry[] = [] - let strayBudget = this.config.maxLogBytes + // ONE host-side ledger for everything that lands in `logs`/`strayLogs`, + // whatever the path: honest port entries, FORGED port entries (model + // code posting `log` messages directly, bypassing the worker-side + // LogBuffer), and stray pipe bytes. On the first overflow it emits the + // same in-band marker the worker's LogBuffer would and drops the rest, + // so the documented cap is one shared `maxLogBytes` however it is hit. + let logBudget = this.config.maxLogBytes + let logsTruncated = false + const admit = (entry: CodeLogEntry, sink: CodeLogEntry[]): void => { + if (logsTruncated) return + const cost = Buffer.byteLength(entry.text, 'utf8') + if (cost > logBudget) { + logsTruncated = true + sink.push({ source: 'stderr', text: logTruncationMarker(this.config.maxLogBytes) }) + return + } + logBudget -= cost + sink.push(entry) + } + + // No settled guard: `finish` snapshots the arrays when it resolves, so + // a chunk flushing after settlement mutates only the discarded buffers, + // and the ledger bounds that growth until the pipes close. const captureStray = (source: 'stdout' | 'stderr') => (chunk: Buffer) => { - if (settled || strayBudget <= 0) return - const text = chunk.toString('utf8').slice(0, strayBudget) - strayBudget -= Buffer.byteLength(text, 'utf8') - strayLogs.push({ source, text }) + admit({ source, text: chunk.toString('utf8') }, strayLogs) } worker.stdout.on('data', captureStray('stdout')) worker.stderr.on('data', captureStray('stderr')) @@ -267,9 +346,14 @@ export class WorkerCodeRuntime extends CodeRuntime { const onDone = (message: WorkerToHost): void => { if (message.type !== 'done') return + // Re-cap the completion value HOST-side: the honest path already + // capped it in the worker (prepareValue there), but a forged done + // message bypasses the bootstrap entirely — without this, model code + // could flood the host past maxValueBytes. Honest values pass + // unchanged (see VALUE_RENDER_SLACK); the error text is bounded too. finish({ - ...message.value !== undefined ? { value: message.value } : {}, - ...message.error ? { error: { kind: 'exception' as const, message: message.error.message } } : {}, + ...prepareValue(message.value, this.config.maxValueBytes + VALUE_RENDER_SLACK), + ...message.error ? { error: { kind: 'exception' as const, message: message.error.message.slice(0, this.config.maxValueBytes) } } : {}, }) } @@ -308,8 +392,12 @@ export class WorkerCodeRuntime extends CodeRuntime { })() } - worker.on('message', (message: WorkerToHost) => { - if (message.type === 'log' && !settled) logs.push(message.entry) + worker.on('message', (raw: unknown) => { + // Parse before touching: the peer can post ANY shape, and a throw in + // this listener would crash the host process. Junk drops silently. + const message = parseWorkerMessage(raw) + if (!message) return + if (message.type === 'log' && !settled) admit(message.entry, logs) onCall(message) onDone(message) }) diff --git a/packages/code-runtime/code-runtime-worker/src/protocol.ts b/packages/code-runtime/code-runtime-worker/src/protocol.ts index 85d5113b82..b8ea122c5b 100644 --- a/packages/code-runtime/code-runtime-worker/src/protocol.ts +++ b/packages/code-runtime/code-runtime-worker/src/protocol.ts @@ -63,3 +63,16 @@ export type WorkerToHost = CallMessage | LogMessage | DoneMessage export type ReplyMessage = | { type: 'reply'; id: number; ok: true; value: unknown } | { type: 'reply'; id: number; ok: false; message: string } + +/** + * The in-band marker entry text announcing that log capture stopped at the + * byte budget. Shared wire vocabulary: the worker's LogBuffer emits it when + * ITS budget exhausts, and the host emits the identical text when its own + * ledger drops an entry first (forged port traffic, stray pipe bytes) — so + * a truncated run reads the same however the cap was hit. + * @param maxBytes - the configured `maxLogBytes` the marker names. + * @returns the marker line. + */ +export function logTruncationMarker(maxBytes: number): string { + return `[dsh-code-runtime-worker] log capture truncated at ${maxBytes} bytes` +} diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts index 8edfdc6a41..a2a3aa4091 100644 --- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts +++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts @@ -101,6 +101,13 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => { expect(typeof result.value).toBe('string') }) + it('completes a program that returns nothing with no value at all', async () => { + const { runtime } = await setup() + const result = await runtime.run({ program: 'const x = 1', bindings: [] }) + expect(result.error).toBeUndefined() + expect('value' in result).toBe(false) + }) + it('keeps logs streamed before a failure', async () => { const { runtime } = await setup() const result = await runtime.run({ @@ -255,6 +262,76 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => { expect(result.value).toBe('still-works') }) + it('survives arbitrary junk on the port: non-objects, junk types, malformed calls, logs, and dones', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: ` + const { parentPort } = await import('node:worker_threads'); + for (const junk of [ + null, 42, 'junk', [], + { type: 'nope' }, + { type: 'call' }, + { type: 'call', id: 'x', global: 'tools', name: 'real', args: {} }, + { type: 'call', id: 1e9, global: 7, name: 'real', args: {} }, + { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} }, + { type: 'log' }, + { type: 'log', entry: null }, + { type: 'log', entry: { source: 'stdout', text: 7 } }, + { type: 'log', entry: { source: 'nope', text: 'x' } }, + { type: 'log', entry: { source: 'console', level: 'nope', text: 'x' } }, + { type: 'log', entry: { source: 'console', level: 7, text: 'x' } }, + { type: 'done', error: 5 }, + { type: 'done', error: { message: 5 } }, + ]) parentPort.postMessage(junk); + return await tools.real({}); + `, + bindings: tools({ real: async () => 'still-works' }), + }) + expect(result.error).toBeUndefined() + expect(result.value).toBe('still-works') + expect(result.logs).toEqual([]) + }) + + it('caps forged log floods and forged done values at the configured budgets, dropping forged extra fields', async () => { + const { runtime } = await setup({ maxLogBytes: 200, maxValueBytes: 64 }) + const result = await runtime.run({ + // Forged messages bypass the worker-side LogBuffer and prepareValue + // entirely — only the host-side ledger and re-cap stand between model + // code and an unbounded result. + program: ` + const { parentPort } = await import('node:worker_threads'); + for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', entry: { source: 'stdout', text: 'F'.repeat(100), forged: true } }); + parentPort.postMessage({ type: 'done', value: 'V'.repeat(100000) }); + for (;;) {} + `, + bindings: [], + }) + expect(typeof result.value).toBe('string') + const value = result.value as string + expect(value.startsWith('V'.repeat(64))).toBe(true) + expect(value.endsWith('… [truncated]')).toBe(true) + expect(value.length).toBeLessThan(120) + const marker = '[dsh-code-runtime-worker] log capture truncated at 200 bytes' + const total = result.logs.reduce((sum, entry) => sum + Buffer.byteLength(entry.text, 'utf8'), 0) + expect(total).toBeLessThanOrEqual(200 + Buffer.byteLength(marker, 'utf8')) + expect(result.logs.at(-1)?.text).toBe(marker) + expect(result.logs.every(entry => !('forged' in entry))).toBe(true) + }) + + it('accepts a forged done carrying both value and error (self-sabotage, contained)', async () => { + const { runtime } = await setup() + const result = await runtime.run({ + program: ` + const { parentPort } = await import('node:worker_threads'); + parentPort.postMessage({ type: 'done', value: 'lied', error: { message: 'fake failure' } }); + for (;;) {} + `, + bindings: [], + }) + expect(result.value).toBe('lied') + expect(result.error).toEqual({ kind: 'exception', message: 'fake failure' }) + }) + it('answers a binding whose resolution cannot be cloned with a failure reply', async () => { const { runtime } = await setup() const result = await runtime.run({ From 3265bdbf70bcf3aab31cf5b14362f35961a8b64d Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 11:43:29 +0800 Subject: [PATCH 040/119] fix(timeout-policy): warn on configured-but-unregistered tool names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ds-review-bot flagged that a typo'd or stale config key (e.g. web_fech for web_fetch) silently applies the timeout to nothing — the tools/execute lookup just never matches. Mirror dsh-tool-subagent's lifecycle-driven handling of a configured-but-unregistered provider: on every tools/change (and once at load), logger.warn each configured name still absent from ctx.tools, warning each name at most once so a late registration silences it. Not a load-time throw — the tool set is dynamic (cordis.yml load order, HMR), so a real tool may register later. Declare inject = ['tools'] since the plugin now reads ctx.tools synchronously in apply (previously only inside event callbacks). Regenerate config-catalog (Requires: tools) and event-producer-consumer graph. --- docs/config-catalog.md | 4 +- docs/event-producer-consumer.md | 2 +- packages/timeout/timeout-policy/README.md | 2 + packages/timeout/timeout-policy/src/index.ts | 35 +++++++++++ .../tests/timeout-policy.spec.ts | 59 ++++++++++++++++++- 5 files changed, 99 insertions(+), 3 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index d1ee1b8a86..20254f3e35 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -604,6 +604,8 @@ Source: [`packages/core/system-prompt/src/index.ts:179`](../packages/core/system ## `@deepseek-ai/dsh-timeout-policy` +Requires: `tools` + ```ts config-catalog /** * Plugin config: per-tool timeout policy, keyed by the model-facing tool name. @@ -623,7 +625,7 @@ export interface ToolTimeoutPolicy { } ``` -Source: [`packages/timeout/timeout-policy/src/index.ts:61`](../packages/timeout/timeout-policy/src/index.ts) +Source: [`packages/timeout/timeout-policy/src/index.ts:64`](../packages/timeout/timeout-policy/src/index.ts) ## `@deepseek-ai/dsh-tool-fs` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 0c95164728..ce8e17e851 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -31,7 +31,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:118`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | +| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:118`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | [`timeout-policy`](../packages/timeout/timeout-policy) | | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:113`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:77`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | diff --git a/packages/timeout/timeout-policy/README.md b/packages/timeout/timeout-policy/README.md index 9054566cc3..bdf189ba7f 100644 --- a/packages/timeout/timeout-policy/README.md +++ b/packages/timeout/timeout-policy/README.md @@ -25,6 +25,8 @@ Per-tool policy, keyed by the model-facing tool name. There is deliberately **no |---|---|---| | `tools` | `Record` | Per-tool timeout policy; an unlisted tool gets no deadline. `timeoutMs` is required per configured tool and must be positive finite. | +A configured tool name that never registers (a typo like `web_fech`, or a stale key) would silently apply the timeout to nothing. Because the tool set is dynamic (plugins register in `cordis.yml` order, HMR re-registers), this is not a load-time error — a real tool may register later. Instead, on every `tools/change` (and once at load) the plugin `logger.warn`s each configured name still absent from `ctx.tools`, warning each name at most once so a late registration silences it. This mirrors `dsh-tool-subagent`'s lifecycle-driven handling of a configured-but-unregistered provider name. + ### Behavior For a **configured** tool the listener: diff --git a/packages/timeout/timeout-policy/src/index.ts b/packages/timeout/timeout-policy/src/index.ts index d092a6203b..b57091fe91 100644 --- a/packages/timeout/timeout-policy/src/index.ts +++ b/packages/timeout/timeout-policy/src/index.ts @@ -46,6 +46,9 @@ export const TOOL_TIMEOUT = 'TOOL_TIMEOUT' /** Cordis plugin name used by loader diagnostics. */ export const name = 'timeout-policy' +/** The tool registry seam this plugin wraps (`tools/execute`) and reads (`tools/change`, `get`). */ +export const inject = ['tools'] + /** Per-tool timeout policy. `timeoutMs` is required and must be positive finite. */ export interface ToolTimeoutPolicy { /** The per-call cooperative deadline for this tool, in milliseconds. */ @@ -103,6 +106,15 @@ export function toolTimeoutResult(callId: CallId, timeoutMs: number): ToolExecut * `tools/post-execute` sees the caller's own signal, and replaces the result * with {@link toolTimeoutResult} when its own timer fired. An unconfigured tool * delegates untouched. + * + * A configured tool name that is never registered is almost always a typo or a + * stale config key (e.g. `web_fech` for `web_fetch`): the wrapper would then + * silently never fire for the intended tool. Since the tool set is dynamic + * (plugins register in `cordis.yml` order, and HMR re-registers), this cannot + * be a load-time hard error — a real tool may register later. Instead, mirror + * `dsh-tool-subagent`'s lifecycle-driven approach: on every `tools/change` (and + * once at apply), `logger.warn` each configured name still absent from the + * registry, warning each name at most once so a late registration silences it. */ export function apply(ctx: Context, config: Config): void { // schemastery (Config) has already filled `tools` with its {} default. @@ -111,6 +123,29 @@ export function apply(ctx: Context, config: Config): void { assertPositiveFinite(toolName, policy.timeoutMs) } + // Warn once per configured name that no registered tool matches, so a typo'd + // or stale config key is visible instead of silently applying to nothing. A + // name that later registers is dropped from `pending` before it is warned; a + // name that never registers is warned at most once (moved to `warned`), so a + // busy `tools/change` stream cannot spam the same key. + const pending = new Set(Object.keys(resolved.tools)) + const warned = new Set() + const warnUnknownToolNames = (): void => { + const nowUnknown: string[] = [] + for (const name of pending) { + if (ctx.tools.get(name) !== undefined) { pending.delete(name); continue } + if (!warned.has(name)) { warned.add(name); nowUnknown.push(name) } + } + if (nowUnknown.length > 0) { + ctx.logger.warn( + `timeout-policy: configured timeout for unregistered tool(s) ${nowUnknown.map(n => `"${n}"`).join(', ')} ` + + '— check for a typo or stale config key; the timeout applies to nothing until the tool registers.', + ) + } + } + ctx.on('tools/change', warnUnknownToolNames) + warnUnknownToolNames() + ctx.on('tools/execute', async (exec, next): Promise => { const timeoutMs = resolved.tools[exec.name]?.timeoutMs // Unconfigured tool: no deadline, delegate unchanged. diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts index 23017d60f1..967e5659ed 100644 --- a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts +++ b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts @@ -84,6 +84,62 @@ describe('timeout-policy config validation', () => { }) }) +describe('timeout-policy unknown-tool-name diagnostics', () => { + it('warns for a configured tool name that is never registered (typo/stale key)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) + // web_fech is a typo for web_fetch, and no tool by that name is registered. + await ctx.plugin(timeoutPolicy, { tools: { web_fech: { timeoutMs: 30_000 } } }) + expect(warn).toHaveBeenCalledTimes(1) + expect(warn.mock.calls[0]?.[0]).toContain('"web_fech"') + expect(warn.mock.calls[0]?.[0]).toContain('unregistered tool') + }) + + it('does NOT warn when the configured tool is already registered at load', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + ctx.tools.register(fastTool) + const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) + await ctx.plugin(timeoutPolicy, { tools: { fast: { timeoutMs: 30_000 } } }) + expect(warn).not.toHaveBeenCalled() + }) + + it('does NOT warn once a configured tool registers LATER (load-order safe)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) + // Plugin loads before the tool it configures — the initial check would warn, + // so register first is the interesting case: mount with a not-yet-present + // name, then register it; the tools/change listener must clear it. + await ctx.plugin(timeoutPolicy, { tools: { late: { timeoutMs: 30_000 } } }) + expect(warn).toHaveBeenCalledTimes(1) // absent at load → warned once + warn.mockClear() + ctx.tools.register({ ...fastTool, name: 'late' }) // now it registers + // A subsequent tools/change must NOT re-warn the now-registered name. + ctx.tools.register({ ...fastTool, name: 'other' }) + expect(warn).not.toHaveBeenCalled() + }) + + it('warns at most once per unknown name across repeated tools/change', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) + await ctx.plugin(timeoutPolicy, { tools: { ghost: { timeoutMs: 30_000 } } }) + expect(warn).toHaveBeenCalledTimes(1) // apply-time check + // Each register/unregister emits tools/change; the ghost stays unknown but + // must not be warned again. + const dispose = ctx.tools.register(fastTool) + dispose() + ctx.tools.register({ ...fastTool, name: 'another' }) + expect(warn).toHaveBeenCalledTimes(1) + }) +}) + describe('timeout-policy delegation (unconfigured / fast)', () => { it('delegates an UNCONFIGURED tool unchanged and does not touch exec.signal', async () => { const ctx = await setup({ other: { timeoutMs: 50 } }) @@ -234,13 +290,14 @@ describe('timeout-policy disposal (HMR safety)', () => { }) describe('dsh-timeout-policy real-load-path guard', () => { - it('has no default export and keeps name/Config through unwrapExports', () => { + it('has no default export and keeps name/inject/Config through unwrapExports', () => { expect('default' in timeoutPolicy).toBe(false) const loader = Object.create(Loader.prototype) as Loader const unwrapped = loader.unwrapExports(timeoutPolicy) as Record expect(unwrapped).toBe(timeoutPolicy) expect(unwrapped.name).toBe('timeout-policy') + expect(unwrapped.inject).toEqual(['tools']) expect(typeof unwrapped.apply).toBe('function') expect(unwrapped.Config).toBeDefined() }) From e20ce35ffb5f20df2874caadef92ce2763e29500 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 12:55:14 +0800 Subject: [PATCH 041/119] fix: self-contained built bundles + wire-size value cap (bot review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two findings from the GitHub review bot on the ready PR: The tsdown two-entry build emitted the shared bootstrap module as a lib/bootstrap-*.js chunk imported by both bundles, which the package.json files whitelist (deliberately exact) omitted — a packed install had dangling imports. The package now runs two single-entry builds, so each bundle inlines its own bootstrap copy and every shipped file is self-contained. prepareValue admitted any cloneable value whose BOUNDED inspect rendering fit maxValueBytes, so a huge container with a compact rendering (a 50k-element array renders as '... N more items') crossed the port raw, bypassing the cap on both sides. The cap now measures the value's real cross-boundary size — exact bytes for strings, the structured-clone wire size (v8.serialize) for everything else — and oversized containers cross as their bounded rendering instead. --- docs/config-catalog.md | 6 ++- .../code-runtime-worker/src/bootstrap.ts | 42 +++++++++++-------- .../code-runtime-worker/src/index.ts | 6 ++- .../tests/bootstrap.spec.ts | 10 +++++ .../code-runtime-worker/tests/runtime.spec.ts | 8 ++++ .../code-runtime-worker/tsdown.config.ts | 39 ++++++++++++----- 6 files changed, 81 insertions(+), 30 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 6339911606..b50ce46d08 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -164,7 +164,11 @@ export interface Config { maxWallMs?: number /** Shared byte budget for captured log text (console + raw stream writes), truncation marked in-band. */ maxLogBytes?: number - /** Byte cap for the rendered completion value; an oversized or non-cloneable value crosses as a capped string rendering. */ + /** + * Byte cap for the completion value, measured by its real cross-boundary + * size (string bytes, or structured-clone wire size); an oversized or + * non-cloneable value crosses as a capped string rendering. + */ maxValueBytes?: number /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */ maxOldGenerationSizeMb?: number diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts index ae6bcf25bf..62374ccaa0 100644 --- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts +++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts @@ -11,6 +11,7 @@ */ import { inspect } from 'node:util' +import { serialize } from 'node:v8' import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime' import { logTruncationMarker } from './protocol.ts' import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' @@ -119,29 +120,36 @@ export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream, so const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const /** - * Prepare the program's completion value for the done message: a - * structured-clone-safe value whose rendering fits `maxValueBytes` crosses - * raw; anything else (non-cloneable, or oversized) is REPLACED by its - * bounded `util.inspect` rendering, truncated with an in-band marker — the - * seam contract's "a non-transferable value is replaced by a string - * rendering", extended to oversized ones so a huge return cannot flood the - * host. + * Prepare the program's completion value for the done message: a value whose + * MEASURED cross-boundary size fits `maxValueBytes` crosses raw — exact + * bytes for a string, the structured-clone wire size (`v8.serialize`) for + * everything else, so a huge container whose BOUNDED inspect rendering + * happens to be small cannot smuggle itself past the cap. Anything else + * (non-cloneable, or oversized) is REPLACED by its bounded `util.inspect` + * rendering, truncated with an in-band marker — the seam contract's "a + * non-transferable value is replaced by a string rendering", extended to + * oversized ones so a huge return cannot flood the host. * @param value - the program's completion value. - * @param maxValueBytes - the byte cap for the rendered value. + * @param maxValueBytes - the byte cap for the value. * @returns the done-message fragment: `{}` for `undefined`, else `{ value }`. */ export function prepareValue(value: unknown, maxValueBytes: number): { value?: unknown } { if (value === undefined) return {} - const rendered = typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS) - let cloneable = true - try { - structuredClone(value) - } catch { - // Only the verdict matters: the value has parts structured clone rejects - // (functions, classes, …) and must cross as its rendering instead. - cloneable = false + if (typeof value === 'string') { + if (Buffer.byteLength(value, 'utf8') <= maxValueBytes) return { value } + } else { + let size: number | undefined + try { + size = serialize(value).byteLength + } catch { + // Only the verdict matters: the value has parts the structured-clone + // algorithm rejects (functions, classes, …) and must cross as its + // rendering instead. + size = undefined + } + if (size !== undefined && size <= maxValueBytes) return { value } } - if (cloneable && Buffer.byteLength(rendered, 'utf8') <= maxValueBytes) return { value } + const rendered = typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS) const capped = rendered.length > maxValueBytes ? `${rendered.slice(0, maxValueBytes)}… [truncated]` : rendered return { value: capped } } diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts index a2385ba83e..7749fb0318 100644 --- a/packages/code-runtime/code-runtime-worker/src/index.ts +++ b/packages/code-runtime/code-runtime-worker/src/index.ts @@ -45,7 +45,11 @@ export interface Config { maxWallMs?: number /** Shared byte budget for captured log text (console + raw stream writes), truncation marked in-band. */ maxLogBytes?: number - /** Byte cap for the rendered completion value; an oversized or non-cloneable value crosses as a capped string rendering. */ + /** + * Byte cap for the completion value, measured by its real cross-boundary + * size (string bytes, or structured-clone wire size); an oversized or + * non-cloneable value crosses as a capped string rendering. + */ maxValueBytes?: number /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */ maxOldGenerationSizeMb?: number diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts index c4e5393634..685c152b10 100644 --- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts +++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts @@ -108,6 +108,16 @@ describe('prepareValue', () => { const { value } = prepareValue('x'.repeat(50), 10) expect(value).toBe(`${'x'.repeat(10)}… [truncated]`) }) + + it('measures a container by its structured-clone wire size, not its bounded rendering', () => { + // The bounded inspect rendering of a huge array is tiny ("... N more + // items"), but its real cross-boundary size is not — the cap must catch + // it, replacing the value with that bounded rendering. + const huge = new Array(50_000).fill(7) + const { value } = prepareValue(huge, 1_000) + expect(typeof value).toBe('string') + expect(value).toContain('more items') + }) }) describe('makeNamespaces', () => { diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts index a2a3aa4091..2d29dc143d 100644 --- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts +++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts @@ -221,6 +221,14 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => { expect(result.value).toBe(`${'y'.repeat(64)}… [truncated]`) }) + it('caps a huge container whose bounded rendering is small (wire size, not rendering, is what counts)', async () => { + const { runtime } = await setup() + const result = await runtime.run({ program: 'return new Array(50_000).fill(7)', bindings: [] }) + expect(result.error).toBeUndefined() + expect(typeof result.value).toBe('string') + expect(result.value).toContain('more items') + }) + it('captures pipe writes that bypass the patched write slot as stray logs, capped by the same budget', async () => { const { runtime } = await setup({ maxLogBytes: 4 }) const result = await runtime.run({ diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts index 234ec4c6b9..5af39d936a 100644 --- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts +++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts @@ -4,15 +4,32 @@ import { defineConfig } from 'tsdown' * Package-shape override (see the root tsdown.config.ts): besides the * default lib/index.js bundle, the worker BOOTSTRAP ships as its own * sibling entry — `new Worker(new URL('./worker.js', import.meta.url))` - * loads it as a file, so it cannot be part of the index bundle. + * loads it as a file, so it cannot be part of the index bundle. TWO + * single-entry builds, not one two-entry build: a multi-entry build emits + * the shared bootstrap module as a `lib/bootstrap-*.js` chunk both bundles + * import, which the package.json `files` whitelist (deliberately exact) + * would omit from the packed artifact — each single-entry build inlines its + * own bootstrap copy instead, keeping every shipped file self-contained. */ -export default defineConfig({ - entry: ['lib/types/index.js', 'lib/types/worker.js'], - outDir: 'lib', - format: ['esm'], - platform: 'node', - target: 'es2024', - fixedExtension: false, - dts: false, - clean: false, -}) +export default defineConfig([ + { + entry: ['lib/types/index.js'], + outDir: 'lib', + format: ['esm'], + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: false, + }, + { + entry: ['lib/types/worker.js'], + outDir: 'lib', + format: ['esm'], + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: false, + }, +]) From b59d245c7c7a6fa505553de039b1d13e508ef446 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 12:58:23 +0800 Subject: [PATCH 042/119] =?UTF-8?q?feat:=20Code=20Mode=20=E2=80=94=20the?= =?UTF-8?q?=20registry's=20mode=20config,=20the=20SDK=20codegen,=20and=20t?= =?UTF-8?q?he=20run=5Fcode=20bridge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dsh-tools half of the Code Mode RFC (its fourth, final change): the registry gains its first config — mode: native | code | both — and OWNS how its tools reach the model. 'code' contributes exactly one wire tool, run_code, plus a lazy tools:sdk prompt section declaring every other tool as a generated TypeScript API (jsonSchemaToTs: total over the defineTool subset, unknown degradation, lexicographic byte-identical rendering); 'both' ships both representations; 'native' is byte-for-byte the old behavior. Non-native modes fail every assembly loudly without a typescript-language ctx.codeRuntime. run_code's dispatch bridge: JSON-normalizes each binding argument before dispatch (what dispatches is what the tool/code-dispatch event logs — the append can never fail on payload shape; BigInt/circulars reject that one call), serializes all program tool calls through a per-run queue (even Promise.all — no concurrency-safety metadata yet), routes every sub-call through tools/pre-execute → tools/post-execute (a deny rejects the program-side promise), drops sub-call additionalContext (no safe outlet mid-run; pinned), owns a run-scoped abort that follows the outer signal in and fires on settlement (in-flight sub-dispatch aborted, queued abandoned, queue drained before returning), and converts a failed run into CodeRunFailedError → a structured isError carrying kind + captured logs. tool/code-dispatch joins SessionEventMap by declaration merging (log-only; deriveMessages ignores it). The composed surface: the tools config forwards through agent-core and both app packages; examples/code-agent + demo:code run the worker runtime under mode code (keyless boot smoke + a with-key e2e proving the collapsed [run_code] header, the dispatch events, and the file the program wrote); two new snapshot scenarios (code-mode-turn, both-mode-turn) record the SDK section, collapsed header, dispatch events, and result card — each its own header-pinning class (the harness gains per-scenario config overlays and per-class pins). Catalogs, graphs, cookbook, hooks-bridge notes, and the RFC (moved to implemented/, restructured to decision-era headings) updated in the same change. --- docs/capability-seams.md | 3 +- docs/config-catalog.md | 62 ++- docs/cookbook/adding-a-tool.md | 4 + docs/cordis-catalog/events.md | 6 +- docs/cordis-catalog/services.md | 4 +- docs/core-data-structures/code-runtime.md | 2 +- docs/event-producer-consumer.md | 6 +- docs/module-graph.md | 10 +- docs/persistence-catalog.md | 12 + docs/rfc/INDEX.md | 2 +- .../feature/2026-06-15-code-mode.md | 38 +- docs/tool-catalog.md | 26 + docs/tool-execution-pipeline.md | 4 +- examples/AGENTS.md | 3 +- examples/README.md | 6 + .../acp-agent/both-mode.cordis.snapshot.yml | 32 ++ examples/acp-agent/both-mode.cordis.yml | 29 + .../acp-agent/code-mode.cordis.snapshot.yml | 32 ++ examples/acp-agent/code-mode.cordis.yml | 29 + examples/acp-agent/tests/acp.snapshot.ts | 106 +++- examples/acp-agent/tests/snapshot-harness.ts | 10 +- .../tests/snapshots/both-mode-turn/input.json | 7 + .../snapshots/both-mode-turn/session.jsonl | 110 ++++ .../both-mode-turn/stdout.golden.jsonl | 55 ++ .../tests/snapshots/code-mode-turn/input.json | 7 + .../snapshots/code-mode-turn/session.jsonl | 196 +++++++ .../code-mode-turn/stdout.golden.jsonl | 98 ++++ examples/code-agent/README.md | 17 + examples/code-agent/cordis.yml | 84 +++ examples/code-agent/package.json | 7 + examples/code-agent/tests/code-mode.e2e.ts | 115 ++++ .../code-agent/tests/keyless-smoke.e2e.ts | 90 +++ package.json | 1 + packages/code-runtime/README.md | 2 +- .../code-runtime-worker/README.md | 2 +- packages/code-runtime/code-runtime/README.md | 2 +- .../code-runtime/code-runtime/src/index.ts | 2 +- packages/core/agent-core/src/index.ts | 20 +- packages/core/tools/README.md | 21 +- packages/core/tools/package.json | 7 + packages/core/tools/src/code-mode.ts | 280 ++++++++++ packages/core/tools/src/index.ts | 102 +++- packages/core/tools/src/ts-types.ts | 121 ++++ packages/core/tools/tests/code-mode.spec.ts | 523 ++++++++++++++++++ .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- packages/core/tools/tests/ts-types.spec.ts | 124 +++++ packages/core/tools/tsconfig.json | 6 + packages/hooks/hooks-claude/README.md | 2 +- packages/hooks/hooks-codex/README.md | 2 +- packages/ui/acp-agent/package.json | 2 + packages/ui/acp-agent/src/index.ts | 8 +- packages/ui/stdio-agent/package.json | 2 + packages/ui/stdio-agent/src/index.ts | 5 + pnpm-lock.yaml | 16 + scripts/gen-doc-graphs.ts | 8 +- scripts/gen-tool-catalog.ts | 25 +- 56 files changed, 2395 insertions(+), 102 deletions(-) rename docs/rfc/{proposed => implemented}/feature/2026-06-15-code-mode.md (84%) create mode 100644 examples/acp-agent/both-mode.cordis.snapshot.yml create mode 100644 examples/acp-agent/both-mode.cordis.yml create mode 100644 examples/acp-agent/code-mode.cordis.snapshot.yml create mode 100644 examples/acp-agent/code-mode.cordis.yml create mode 100644 examples/acp-agent/tests/snapshots/both-mode-turn/input.json create mode 100644 examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl create mode 100644 examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl create mode 100644 examples/acp-agent/tests/snapshots/code-mode-turn/input.json create mode 100644 examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl create mode 100644 examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl create mode 100644 examples/code-agent/README.md create mode 100644 examples/code-agent/cordis.yml create mode 100644 examples/code-agent/package.json create mode 100644 examples/code-agent/tests/code-mode.e2e.ts create mode 100644 examples/code-agent/tests/keyless-smoke.e2e.ts create mode 100644 packages/core/tools/src/code-mode.ts create mode 100644 packages/core/tools/src/ts-types.ts create mode 100644 packages/core/tools/tests/code-mode.spec.ts create mode 100644 packages/core/tools/tests/ts-types.spec.ts diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 12ce8033b9..970414d4df 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -102,6 +102,7 @@ flowchart LR svc_bash --> pkg_hooks_claude svc_bash --> pkg_hooks_codex svc_bash --> pkg_tool_bash + svc_codeRuntime --> pkg_tools svc_compact --> pkg_compact_basic svc_fs --> pkg_tool_fs svc_llm --> pkg_agent_loop @@ -139,7 +140,7 @@ flowchart LR | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. | -| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | - | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer). | +| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). | | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. | | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. | | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 6339911606..b700431f1d 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -42,7 +42,8 @@ Source: [`packages/ui/acp/src/index.ts:115`](../packages/ui/acp/src/index.ts) * pre-created agent — ACP creates agents at `session/new`); `persona` is the * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is * the explicit model-facing tool order (forwarded to the system-prompt plugin); - * `persistenceRoot` is the JSONL backend's directory. + * `tools` is the tool registry's config (its presentation `mode`, forwarded + * through agent-core); `persistenceRoot` is the JSONL backend's directory. */ export interface Config { /** Model name for ACP-created agents (must have a registered adapter). */ @@ -51,12 +52,16 @@ export interface Config { persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ toolOrder?: string[] + /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */ + tools?: ToolsConfig /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string } ``` -Source: [`packages/ui/acp-agent/src/index.ts:49`](../packages/ui/acp-agent/src/index.ts) +Depends on: [`ToolsConfig`](#deepseek-aidsh-tools) + +Source: [`packages/ui/acp-agent/src/index.ts:51`](../packages/ui/acp-agent/src/index.ts) ## `@deepseek-ai/dsh-agent-core` @@ -66,10 +71,12 @@ Source: [`packages/ui/acp-agent/src/index.ts:49`](../packages/ui/acp-agent/src/i * `agents` to the agent loop (an app that pre-creates no agents, like the ACP * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt * plugin (the deployment's persona section and the explicit model-facing tool - * order). Every field is optional INPUT here because each owner's schema - * supplies the default (`[]` / `''` / absent — lexicographic); the schema is - * the INTERSECTION of the owners' own schemas, so validation and defaulting - * can never drift from them. + * order), the `tools` object to the tool registry (its presentation `mode`). + * Every field is optional INPUT here because each owner's schema + * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the + * schema is the INTERSECTION of the owners' own schemas (the registry's + * nested under its `tools` key), so validation and defaulting can never + * drift from them. */ export interface Config { /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */ @@ -78,12 +85,14 @@ export interface Config { persona?: SystemPromptConfig['persona'] /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */ toolOrder?: SystemPromptConfig['toolOrder'] + /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */ + tools?: ToolsConfig } ``` -Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) +Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools) -Source: [`packages/core/agent-core/src/index.ts:69`](../packages/core/agent-core/src/index.ts) +Source: [`packages/core/agent-core/src/index.ts:71`](../packages/core/agent-core/src/index.ts) ## `@deepseek-ai/dsh-agent-loop` @@ -456,6 +465,8 @@ export interface Config { persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ toolOrder?: string[] + /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */ + tools?: ToolsConfig /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */ @@ -469,7 +480,9 @@ export interface Config { } ``` -Source: [`packages/ui/stdio-agent/src/index.ts:60`](../packages/ui/stdio-agent/src/index.ts) +Depends on: [`ToolsConfig`](#deepseek-aidsh-tools) + +Source: [`packages/ui/stdio-agent/src/index.ts:61`](../packages/ui/stdio-agent/src/index.ts) ## `@deepseek-ai/dsh-subagent-acp` @@ -703,6 +716,36 @@ export interface Config { Source: [`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts) +## `@deepseek-ai/dsh-tools` + +Requires: `systemPrompt` + +```ts config-catalog +/** Plugin config: how the registered tools are presented to the model. */ +export interface Config { + /** + * The presentation mode. `'native'` (the default) contributes every + * registered tool as a wire function definition — byte-for-byte today's + * behavior. `'code'` contributes exactly ONE wire tool, `run_code`, plus + * the generated `tools:sdk` prompt section declaring every other tool as a + * TypeScript API the program calls. `'both'` contributes every native + * definition AND `run_code` + the SDK section. Non-native modes require a + * loaded `ctx.codeRuntime` whose `language` is `'typescript'` — a missing + * or mismatched runtime rejects every prompt assembly with an actionable + * error (misconfiguration fails loud, before any model request). A + * configured `systemPrompt.toolOrder` naming native tools likewise rejects + * every assembly under `'code'` (those names are no longer contributed) — + * a deployment switching modes updates its order config or drops it. + */ + mode?: ToolPresentationMode +} + +/** How the registry presents its tools to the model (see {@link Config.mode}). */ +export type ToolPresentationMode = 'native' | 'code' | 'both' +``` + +Source: [`packages/core/tools/src/index.ts:290`](../packages/core/tools/src/index.ts) + ## `@deepseek-ai/dsh-web` ```ts config-catalog @@ -827,7 +870,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)) - `@deepseek-ai/dsh-tool-bash` — requires `tools` · `bash` · `systemPrompt` ([`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)) - `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts)) -- `@deepseek-ai/dsh-tools` — requires `systemPrompt` ([`packages/core/tools/src/index.ts`](../packages/core/tools/src/index.ts)) ## Seam packages (not directly loadable) diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md index 9180d88489..50c7cbccf8 100644 --- a/docs/cookbook/adding-a-tool.md +++ b/docs/cookbook/adding-a-tool.md @@ -49,6 +49,10 @@ Follow tool-bash's background pattern: a `run_in_background` flag returns a task Prefer not to build policy into the tool. The seam is the `tools/pre-execute` gate (deny/ask — see the permission-gate example in [extension-cookbook.md](./extension-cookbook.md)) and the `tools/post-execute` inspect/transform seam, or a sandboxing implementation behind the tool's executor seam. +## Code Mode reaches your tool for free + +Under the registry's non-native `mode` ([Code Mode](../../packages/core/tools/README.md)), a registered tool is ALSO callable from a `run_code` program as `await tools.(args)` — nothing to add. The generated SDK declares your parameters from the same JSON Schema `defineTool` emits (constructs outside that subset degrade to `unknown`), each program call re-enters `execute()` through both waterfalls, and a failed call rejects the program-side promise with your error text. Two consequences worth designing for: your `description` and parameter `description`s become JSDoc a model reads while WRITING CODE, and non-text result blocks reach programs as placeholders (text is the lingua franca of the bridge). + ## How your tool renders in an editor (ACP presentation) Your tool's `execute` returns model-facing content; its **editor card** is a separate, optional concern you declare with two pure display methods on the `defineTool` options. Design this alongside `execute`, not after — an editor (Zed, over the ACP bridge) shows the card, and a tool with no presentation falls back to a bland generic card (title = tool name, raw args as input). diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 8d776a75ef..309545554a 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -307,7 +307,7 @@ A tool was registered or unregistered (the available tool set changed). 'tools/change'(): void ``` -Source: [`packages/core/tools/src/index.ts:97`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:111`](../../packages/core/tools/src/index.ts) ### `tools/post-execute` — waterfall @@ -319,7 +319,7 @@ Waterfall AFTER a tool runs — where hook plugins inspect the result and accept Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:92`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:106`](../../packages/core/tools/src/index.ts) ### `tools/pre-execute` — waterfall @@ -331,7 +331,7 @@ Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook pl Types: [ToolExecution](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:76`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:90`](../../packages/core/tools/src/index.ts) ## Inherited events (cordis core + loader/hmr/timer) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 26126c4481..4c1c1a18e5 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -213,7 +213,7 @@ Source: [`packages/core/system-prompt/src/index.ts:291`](../../packages/core/sys ## `ctx.tools` — `ToolRegistry` -Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly. +Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly — WHICH schemas is governed by its `mode` config (see Config.mode); under a non-native mode it also registers the `run_code` tool and the `tools:sdk` prompt section itself. ```ts cordis-catalog register(definition: ToolDefinition): () => void @@ -224,7 +224,7 @@ async execute(exec: ToolExecution): Promise Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:278`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:316`](../../packages/core/tools/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/core-data-structures/code-runtime.md b/docs/core-data-structures/code-runtime.md index 1f87e8e8a4..cb1661e02f 100644 --- a/docs/core-data-structures/code-runtime.md +++ b/docs/core-data-structures/code-runtime.md @@ -1,6 +1,6 @@ # Code Runtime -The code-execution seam — a [capability seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) whose interface ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread backend and the tool-registry consumer (Code Mode) are specified in the [Code Mode RFC](../rfc/proposed/feature/2026-06-15-code-mode.md). +The code-execution seam — a [capability seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) whose interface ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread backend and the tool-registry consumer (Code Mode) are specified in the [Code Mode RFC](../rfc/implemented/feature/2026-06-15-code-mode.md). Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts) diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index c10d7caa52..a4d640f44b 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -31,8 +31,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | -| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:76`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:111`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | +| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:106`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:90`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`. diff --git a/docs/module-graph.md b/docs/module-graph.md index fa02da2430..28627c833d 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -112,7 +112,9 @@ flowchart TD pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session pkg_tools --> pkg_agent + pkg_tools --> pkg_code_runtime pkg_tools --> pkg_llm + pkg_tools --> pkg_session pkg_tools --> pkg_system_prompt pkg_compact_basic --> pkg_agent pkg_compact_basic --> pkg_compact @@ -201,12 +203,14 @@ flowchart TD pkg_acp_agent --> pkg_agent_core pkg_acp_agent --> pkg_app_boot pkg_acp_agent --> pkg_session_persistence_jsonl + pkg_acp_agent --> pkg_tools pkg_stdio_agent --> pkg_agent pkg_stdio_agent --> pkg_agent_core pkg_stdio_agent --> pkg_app_boot pkg_stdio_agent --> pkg_llm pkg_stdio_agent --> pkg_session pkg_stdio_agent --> pkg_session_persistence_jsonl + pkg_stdio_agent --> pkg_tools ``` | Package | Group | Depends on | @@ -235,7 +239,7 @@ flowchart TD | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) | | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) | | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt) | +| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | @@ -256,5 +260,5 @@ flowchart TD | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | -| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | -| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | +| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools) | +| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 58fd548665..116b0f6038 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -209,6 +209,18 @@ Types: [CallId](core-data-structures/core.md) Source: [`packages/core/session/src/types.ts:317`](../packages/core/session/src/types.ts) +#### `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. 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 +'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; resultSummary: string } +``` + +Types: [CallId](core-data-structures/core.md) + +Source: [`packages/core/tools/src/code-mode.ts:36`](../packages/core/tools/src/code-mode.ts) + #### `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). diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index b0134ac712..88758efad3 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -10,7 +10,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; |---|---| | [Agent Client Protocol (ACP) support — drive the coding agent from external editors](proposed/feature/2026-06-14-acp-agent-client-protocol.md) | 2026-06-14 | | [Multiplex concurrent ACP sessions over one connection](proposed/feature/2026-06-14-acp-multi-session.md) | 2026-06-14 | -| [Code Mode — the model writes TypeScript against the tool registry](proposed/feature/2026-06-15-code-mode.md) | 2026-06-15 | | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 | ### Simplification @@ -49,6 +48,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | Title | First proposed | |---|---| +| [Code Mode — the model writes TypeScript against the tool registry](implemented/feature/2026-06-15-code-mode.md) | 2026-06-15 | | [Filesystem tool schemas — model-facing read/write/edit shapes](implemented/feature/2026-06-17-filesystem-tool-schemas.md) | 2026-06-17 | | [Rich ACP bash rendering — the terminal card via the `_meta` convention](implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) | 2026-06-18 | | [Compaction as a capability seam (abstract contract + basic backend)](implemented/feature/2026-06-18-compaction-capability-seam.md) | 2026-06-18 | diff --git a/docs/rfc/proposed/feature/2026-06-15-code-mode.md b/docs/rfc/implemented/feature/2026-06-15-code-mode.md similarity index 84% rename from docs/rfc/proposed/feature/2026-06-15-code-mode.md rename to docs/rfc/implemented/feature/2026-06-15-code-mode.md index b9a408241e..2f643b432e 100644 --- a/docs/rfc/proposed/feature/2026-06-15-code-mode.md +++ b/docs/rfc/implemented/feature/2026-06-15-code-mode.md @@ -1,6 +1,6 @@ # RFC: Code Mode — the model writes TypeScript against the tool registry -Status: proposed +Status: implemented ## Problem @@ -12,7 +12,7 @@ Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) proposes an alt An earlier draft of this RFC designed Code Mode as an add-on consumer plugin with zero core changes, deferring the execution substrate to a follow-up. Both constraints are dropped here, deliberately. First, the harness is pre-release and optimizes for the correct foundation over blast radius: tool presentation is the registry's own concern, and bolting a second presentation onto it from outside means transforming the registry's contribution after the fact — a waterfall listener whose correctness depends on listener ordering, which fights the [reconstructable-requests](../../implemented/architecture/2026-07-05-reconstructable-requests.md) design instead of riding it (that refactor removed request mutation from `agent/request`, the seam the old draft relied on). Second, the substrate question is answerable now: a Node `worker_threads` runtime gives real containment — separate isolate, empty environment, heap caps, and a `terminate()` that reliably stops a hot synchronous loop — where the old draft's `node:vm` stub had none of those, and it fits the harness's existing trust model (§Trust posture) without a hardening follow-up. -## Proposal +## Decision Three decisions, each elaborated in its own section below: @@ -82,16 +82,25 @@ The worker runtime is **containment, not a security boundary**, and the RFC says The `tools:sdk` section carries the `.d.ts` plus fixed instructions: the program is the body of an async TypeScript function (erasable syntax only — no `enum`/namespaces; type annotations are advisory); call tools as `await tools.name(args)` (quoted access for exotic names); a failed tool call **rejects** with an `Error` carrying the tool's error text — catch it to handle and continue; calls run **sequentially** even under `Promise.all`; emit results via `return` and/or `console.log`, and only that curated output returns to the context — intermediate tool results never do. That last line is the payoff the whole design serves: output-side context cost becomes the model's own editorial decision. On the input side the `.d.ts` is not free — for a large tool surface it can rival the native JSON schemas it replaces (and `'both'` pays for the two side by side) — but it is prefix-stable, so provider prefix caching amortizes it; the win is workload-dependent and the RFC claims no more. -## Plan +## Consequences -Four stacked PRs, each gates-green (`typecheck`, `lint`, `test:coverage`, `test:snapshot`, `doc-sync`, `verify-module-graph`, `build`, `hygiene`) with docs updated in the same change: +The design shipped as four stacked changes — this RFC, the `dsh-code-runtime` interface package, the `dsh-code-runtime-worker` backend, and the `dsh-tools` integration — each gates-green with docs in the same change; review fixes landed on the change that introduced them and merged down. -1. **This RFC revision** (docs-only): the file rewritten as above (renamed `2026-06-15-code-mode.md`, same first-proposed date), regenerated RFC index. -2. **`dsh-code-runtime`** (interface package): the group `packages/code-runtime/`, abstract `CodeRuntime`, vocabulary types, ctx-key declaration; docs in the same change — group README + package README, the `packages/README.md` group table row, the `ctx.codeRuntime` row in [docs/architecture.md](../../../architecture.md)'s service map, and the regenerated cordis catalog (the new service class). Unit tier: HMR safety (dispose removes `ctx.codeRuntime`), contract docs. This package has no behavior to snapshot or e2e; its coverage story is unit-only by design. -3. **`dsh-code-runtime-worker`**: the implementation above, plus the regenerated config catalog (its `Config`). Unit tier (real workers, no mocks — they are cheap and local): output/value capture, log source attribution, error kinds (exception incl. non-erasable syntax, abort, worker-exit under OOM), the two budgets from both sides (a hot loop with an un-awaited pending dispatch still dies at `computeMs` busy time; a program idling on a slow binding outlives `computeMs` and dies only at `maxWallMs`), binding bridge hostility cases (unknown name, duplicate id, post-settlement message, `__proto__`/`constructor`/`toString` binding names), structured-clone fallback, cap truncation, `env` emptiness verified from inside the program, dispose-awaits-exit. A real-load-path test runs the built package (`lib/`) so the worker entry resolves both unbuilt (tsx) and built — the published-bin guard from [docs/testing.md](../../../testing.md). -4. **Native code mode in `dsh-tools`** + the end-to-end surface: mode config, provider switch, `tools:sdk` section, `jsonSchemaToTs`, `run_code` + dispatch bridge + serialization queue, `tool/code-dispatch` event; regenerated tool, config, and persistence catalogs; [docs/architecture.md](../../../architecture.md) (tool-pipeline prose) and the [adding-a-tool cookbook](../../../cookbook/adding-a-tool.md) cross-reference updated in the same change; an `examples/` leaf + `demo:code` script wiring the worker runtime with `mode: 'code'`; move this RFC to `implemented/`. Coverage named per tier now, per the plan-time rule: **unit** — codegen table (DSL subset, quoted names, `unknown` degradation, determinism), provider contribution per mode, `toolOrder × mode` rejection, missing-runtime/wrong-language loud failures, serialization non-overlap (a probe tool records enter/exit under `Promise.all`), abort stops the queue, binding rejection on `isError`, `CodeRunFailedError` → structured `isError`, event payloads, `deriveMessages()` ignores the event, HMR safety (mode flip via config reload removes tool + section); **e2e (with-key, self-skips)** — a real model, `mode: 'code'`, a task requiring two tool calls and curation, asserting the wire tool list was exactly `run_code` and the transcript's dispatch events; **snapshot (keyless replay)** — goldens for a `run_code` turn in `'code'` and `'both'`, pinning the SDK section text, the collapsed header tools, dispatch events, and the result card. +What exists now: -The four PRs land in order (each on the previous); per stacked-review practice, review fixes land on the PR that introduced them and merge down. +- **The seam**: `packages/code-runtime/` — `@deepseek-ai/dsh-code-runtime` (abstract `CodeRuntime`, the vocabulary above, `ctx.codeRuntime`) and `@deepseek-ai/dsh-code-runtime-worker` (the worker-thread backend, every cap a validated config field). Rows in the service map, capability-seams graph, config catalog, and cordis catalog. +- **The registry surface**: `ToolRegistry`'s first config (`mode`), the mode-aware wire contribution, the `tools:sdk` section, `jsonSchemaToTs`/`renderToolsSdk` (exported), `run_code` + the dispatch bridge + `CodeRunFailedError`, and the `tool/code-dispatch` log event (declaration-merged into `SessionEventMap`, regenerated into the persistence catalog; `run_code` in the tool catalog). +- **The composed surface**: the `tools` config forwards through `agent-core` and both app packages (`stdio-agent`, `acp-agent`); `examples/code-agent` + `demo:code` run the worker runtime under `mode: 'code'`; the adding-a-tool cookbook states that a registered tool is reachable from programs for free, and the tool-pipeline doc shows sub-dispatches re-entering both waterfalls. +- **Interactions inherited by deployments**: a `toolOrder` naming native tools rejects every assembly under `'code'` (update or drop the order config when switching modes); sub-call `additionalContext` is dropped by the bridge (a plural context channel is deferred until a real hook needs it through Code Mode); sub-dispatch stays serialized until tools can declare concurrency safety — the same metadata the native parallel-dispatch TODO waits on. + +## Testing + +What the suites pin, per tier: + +- **Unit — worker runtime** (real workers, no mocks): output/value capture and log-source attribution; error kinds (exception incl. non-erasable syntax, abort, worker-exit under OOM); the two budgets from both sides (a hot loop behind an un-awaited pending dispatch dies at `computeMs` busy time; a program idling on a slow binding outlives `computeMs` and dies only at `maxWallMs`); binding-bridge hostility (junk/forged port traffic incl. non-object messages and forged `log`/`done` cap bypass attempts, unknown names, duplicate ids, post-settlement replies, `__proto__`/`constructor`/`toString` binding names); structured-clone fallback and cap truncation; `env` emptiness verified from inside a program; dispose-awaits-exit. A real-load-path e2e runs the BUILT package under plain `node` so the worker entry resolves both unbuilt (tsx) and built — the published-artifact guard from [docs/testing.md](../../../testing.md). +- **Unit — registry integration**: the codegen table (DSL subset, quoted names, `unknown` degradation, byte-identical determinism); provider contribution per mode (`'native'` unchanged, `'code'` exactly `[run_code]`, `'both'` all + `run_code`); `toolOrder × mode` rejection; missing-runtime / wrong-language loud failures; serialization non-overlap (a probe tool records enter/exit under `Promise.all`); abort aborting the in-flight sub-dispatch and abandoning queued ones; binding rejection on `isError` and on JSON-unrepresentable arguments; `CodeRunFailedError` → structured `isError` carrying kind + logs; `tool/code-dispatch` payloads (JSON-normalized arguments identical to what dispatched); `deriveMessages()` ignoring the event; sub-call `additionalContext` suppression; HMR safety (disposing the registry removes the tool and the section). +- **e2e (with-key, self-skips)**: a real model under `mode: 'code'` composes two bash calls in one program (`examples/code-agent/tests/code-mode.e2e.ts`) — every logged `request/header` carries exactly `[run_code]`, the dispatch events land under the parent call, the file the program wrote exists, and the final answer is the curated output. +- **Snapshot (keyless replay)**: goldens for a `run_code` turn under `'code'` and `'both'` (`code-mode-turn`, `both-mode-turn`), each its own header-pinning class — the SDK section text, the collapsed header tool list, the dispatch events, and the result card are committed and replayed. ## Alternatives considered @@ -111,17 +120,6 @@ The four PRs land in order (each on the previous); per stacked-review practice, **A REPL-style persistent kernel** (state survives across `run_code` calls). Rejected for the MVP: cross-call state would be invisible to the session log, breaking the reconstructability guarantee that every request is a pure function of the log; fresh-per-run keeps it. A kernel-style backend remains expressible behind the seam later, with its own logging story. -## Acceptance criteria - -- `mode: 'native'` (and unset) is byte-for-byte today's behavior: same assemblies, same headers, same snapshots. -- Under `mode: 'code'`, the assembled tool list (and thus the logged `request/header`) is exactly `[run_code]`; under `'both'`, every native schema plus `run_code`; the `tools:sdk` section is present in both, absent under `'native'`, and its text is deterministic for a fixed tool set (byte-identical across consecutive assemblies). -- The generated `.d.ts` covers every registered tool except `run_code`, non-identifier names via quoted keys, unsupported schema constructs as `unknown`, without codegen ever throwing. -- A program calling two tools returns only its curated output; each sub-call appears as a `tool/code-dispatch` event ordered by log `seq`, flows through `tools/pre-execute`/`post-execute` (a deny reaches the program as a binding rejection), and never enters derived messages; a binding argument that does not survive JSON normalization (`BigInt`, a circular structure) rejects before dispatch — nothing executes unlogged. -- `Promise.all` over three bindings produces non-overlapping `ctx.tools.execute()` intervals (probe-tool assertion); aborting mid-program stops the worker and dispatches nothing further; a budget expiry during a slow sub-dispatch aborts that dispatch (the probe tool observes its signal fire), `run_code` returns only after the queue drains, and no `tool/code-dispatch` event lands after `run_code`'s own `tool/result` in the log. -- Worker runtime: a hot `for(;;){}` run ends at the `computeMs` busy-time budget with `error.kind: 'timeout'` — including when the program fired an un-awaited binding call first (the pending-RPC decoy); a program idling on a slow binding does not consume `computeMs` and is bounded only by `maxWallMs`; OOM under `resourceLimits` yields `kind: 'worker-exit'` with the host process healthy; `process.env` inside a program is empty; non-erasable syntax yields `kind: 'exception'` without a worker spawn; disposal awaits worker exit. -- Misconfiguration is loud before any model request: non-native mode with no `ctx.codeRuntime`, a runtime whose `language ≠ 'typescript'`, and `toolOrder` naming a non-contributed tool all reject the assembly with actionable messages. -- The demo runs against the real API via `demo:code`; the snapshot goldens replay keylessly; all repo gates pass on every PR of the stack. - ## Risks **The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index a621d3299d..acfb8e0069 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -15,12 +15,38 @@ This table connects model-visible tool names to the plugin package and service s | Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note | | --- | --- | --- | --- | --- | --- | +| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch per bridged sub-call`, `tool/result` | - | Registered by the tool registry itself under `mode: code` / `mode: both` (see the Code Mode RFC). Under `code` it is the ONLY wire tool; the other registered tools are declared to the model as a generated TypeScript SDK prompt section instead, and a program calls them through port-bridged bindings that dispatch through the ordinary tools/pre-execute → tools/post-execute pipeline, one at a time. | | `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. | | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. | | `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. | +## `@deepseek-ai/dsh-tools` + +### `run_code` + +Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it. + +```json +{ + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "The program: the body of an async TypeScript function." + } + }, + "required": [ + "code" + ] +} +``` + +Source: [`packages/core/tools/src/code-mode.ts`](../packages/core/tools/src/code-mode.ts) + +Registered by the tool registry itself under `mode: code` / `mode: both` (see the Code Mode RFC). Under `code` it is the ONLY wire tool; the other registered tools are declared to the model as a generated TypeScript SDK prompt section instead, and a program calls them through port-bridged bindings that dispatch through the ordinary tools/pre-execute → tools/post-execute pipeline, one at a time. + ## `@deepseek-ai/dsh-tool-bash` ### `bash` diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md index db50a3beec..73711afc1f 100644 --- a/docs/tool-execution-pipeline.md +++ b/docs/tool-execution-pipeline.md @@ -14,7 +14,7 @@ flowchart TD denied["deny or ask
tool body skipped"] toolBody["Registered tool execute() body"] fsGate["fs/write-intent or fs/edit-intent
tool-fs mutations only"] - owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result"] + 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"] context["Buffered additionalContext
context/message after all tool results"] toolResult["Session event: tool/result
single model-facing outcome"] @@ -34,6 +34,6 @@ flowchart TD toolResult --> presentResult ``` -Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. +Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. Code Mode rides the same pipeline twice over: `run_code` is itself a registered tool body, and each tool call its program makes re-enters `ctx.tools.execute()` through BOTH waterfalls — serialized one at a time, logged as a `tool/code-dispatch` session event, with a deny surfacing to the program as a binding rejection (a sub-call's `additionalContext` is deliberately dropped — no safe outlet mid-run preserves call/result adjacency). Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs. diff --git a/examples/AGENTS.md b/examples/AGENTS.md index 6c1cc717df..177ee18aa0 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — Examples -Runnable demos that show how the harness is wired. **Examples are NOT workspaces** — each `examples/*/package.json` is a private, dependency-free stub with no build. They are booted as unbuilt `tsx` subprocesses via the cordis Loader reading a `cordis.yml`; the `@deepseek-ai/dsh-*` plugin names in those YAML files resolve through the root `tsconfig.json` `paths` map, not through `node_modules`. +Runnable demos showing how the harness is wired. **Examples are NOT workspaces** — each `examples/*/package.json` is a private, dependency-free stub, never built. They are booted as unbuilt `tsx` subprocesses via the cordis Loader reading a `cordis.yml`; the `@deepseek-ai/dsh-*` plugin names in those YAML files resolve through the root `tsconfig.json` `paths` map, not through `node_modules`. Because examples are not under the `packages/*/src` coverage gate, an example that grows real, reusable *logic* should extract it into a `packages/` package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: the `cordis.yml` wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios. There is no `start.ts` — the boot glue (Loader tail, `.env` load, snapshot-mode selection, stdin-dispose lifecycle) lives in each app package's `bin` (`@deepseek-ai/dsh-stdio-agent`, `@deepseek-ai/dsh-acp-agent`), which the `demo:*` scripts invoke against the leaf `cordis.yml`. @@ -21,6 +21,7 @@ A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_P |---|---|---| | `echo-agent` | `tests/echo.e2e.ts` — boots the real `cordis.yml`, drives the echo tool round-trip and the direct canned reply | **N/A — keyless by nature** (the `mock-echo` model has no real provider) | | `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified | +| `code-agent` | `tests/keyless-smoke.e2e.ts` — the Code Mode boot guard | `tests/code-mode.e2e.ts` — a real model composes two bash calls in one `run_code` program; collapsed header, dispatch events, written file all verified | | `acp-agent` | `pnpm run test:snapshot` — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); `tests/acp.e2e.ts` also asserts stdout purity without a key | `tests/acp.e2e.ts` — real ACP prompt, verifies a file the agent wrote; `tests/hooks.e2e.ts` — a real `PreToolUse` hook blocks bash, verifies the file is NOT written | See [the root AGENTS.md](../AGENTS.md) for repo-wide conventions and [docs/architecture.md](../docs/architecture.md) for the design. diff --git a/examples/README.md b/examples/README.md index 1e3134ba2d..1b9cdf080e 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,6 +19,12 @@ A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + th Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details. +## code-agent + +The coding agent flipped to **Code Mode**: the worker-thread code runtime is loaded and the tool registry runs `mode: code`, so the model gets exactly one wire tool — `run_code` — plus a generated TypeScript SDK section, and composes bash/read/write/edit/todo_write by writing a program whose output it curates. + +Run with: `pnpm run demo:code` (needs `DEEPSEEK_API_KEY`). See [code-agent/README.md](code-agent/README.md) for what to try and how it differs from coding-agent. + ## acp-agent An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. diff --git a/examples/acp-agent/both-mode.cordis.snapshot.yml b/examples/acp-agent/both-mode.cordis.snapshot.yml new file mode 100644 index 0000000000..67044b8066 --- /dev/null +++ b/examples/acp-agent/both-mode.cordis.snapshot.yml @@ -0,0 +1,32 @@ +# Both-mode REPLAY overlay: the same patched tree as both-mode.cordis.yml +# (registry in `mode: both` + the worker code runtime) with the keyless model +# swap from cordis.snapshot.yml (llm-deepseek disabled, llm-replay serving +# the recorded fixture). Patches do not compose across nested includes — +# an outer include's patch can only target entries in the file IT loads — so +# this file patches ./cordis.yml directly with the union of both overlays. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ./cordis.yml + patches: + - id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + disabled: true + - id: acp-agent + name: '@deepseek-ai/dsh-acp-agent' + config: + model: deepseek-v4-flash + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + tools: + mode: both + persona: | + You are a coding assistant powered by the {{model}} model. Your working + directory is {{cwd}}. + + Verify your work by running the code or tests. Keep answers brief and + factual. + - insert: + - id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' + - id: llm-replay + name: '@deepseek-ai/dsh-llm-replay' diff --git a/examples/acp-agent/both-mode.cordis.yml b/examples/acp-agent/both-mode.cordis.yml new file mode 100644 index 0000000000..b449a568ec --- /dev/null +++ b/examples/acp-agent/both-mode.cordis.yml @@ -0,0 +1,29 @@ +# Both-mode RECORD overlay: the live acp-agent tree (./cordis.yml) with two +# load-time patches — the app entry's config gains `tools: { mode: both }` +# (every native tool definition stays on the wire AND run_code + the generated +# TypeScript SDK prompt section ride along) and the worker-thread code runtime joins the +# tree as `ctx.codeRuntime`. The dsh-acp-agent bin boots this file when the +# snapshot harness records the both-mode scenario; DSH_SNAPSHOT=replay swaps +# it for the sibling both-mode.cordis.snapshot.yml. A config patch REPLACES +# the entry's whole config, so the base entry's fields are restated verbatim. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ./cordis.yml + patches: + - id: acp-agent + name: '@deepseek-ai/dsh-acp-agent' + config: + model: deepseek-v4-flash + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + tools: + mode: both + persona: | + You are a coding assistant powered by the {{model}} model. Your working + directory is {{cwd}}. + + Verify your work by running the code or tests. Keep answers brief and + factual. + - insert: + - id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' diff --git a/examples/acp-agent/code-mode.cordis.snapshot.yml b/examples/acp-agent/code-mode.cordis.snapshot.yml new file mode 100644 index 0000000000..bcaa225eba --- /dev/null +++ b/examples/acp-agent/code-mode.cordis.snapshot.yml @@ -0,0 +1,32 @@ +# Code Mode REPLAY overlay: the same patched tree as code-mode.cordis.yml +# (registry in `mode: code` + the worker code runtime) with the keyless model +# swap from cordis.snapshot.yml (llm-deepseek disabled, llm-replay serving +# the recorded fixture). Patches do not compose across nested includes — +# an outer include's patch can only target entries in the file IT loads — so +# this file patches ./cordis.yml directly with the union of both overlays. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ./cordis.yml + patches: + - id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + disabled: true + - id: acp-agent + name: '@deepseek-ai/dsh-acp-agent' + config: + model: deepseek-v4-flash + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + tools: + mode: code + persona: | + You are a coding assistant powered by the {{model}} model. Your working + directory is {{cwd}}. + + Verify your work by running the code or tests. Keep answers brief and + factual. + - insert: + - id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' + - id: llm-replay + name: '@deepseek-ai/dsh-llm-replay' diff --git a/examples/acp-agent/code-mode.cordis.yml b/examples/acp-agent/code-mode.cordis.yml new file mode 100644 index 0000000000..244cad9209 --- /dev/null +++ b/examples/acp-agent/code-mode.cordis.yml @@ -0,0 +1,29 @@ +# Code Mode RECORD overlay: the live acp-agent tree (./cordis.yml) with two +# load-time patches — the app entry's config gains `tools: { mode: code }` +# (the registry offers exactly one wire tool, run_code, plus the generated +# TypeScript SDK prompt section) and the worker-thread code runtime joins the +# tree as `ctx.codeRuntime`. The dsh-acp-agent bin boots this file when the +# snapshot harness records the code-mode scenarios; DSH_SNAPSHOT=replay swaps +# it for the sibling code-mode.cordis.snapshot.yml. A config patch REPLACES +# the entry's whole config, so the base entry's fields are restated verbatim. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ./cordis.yml + patches: + - id: acp-agent + name: '@deepseek-ai/dsh-acp-agent' + config: + model: deepseek-v4-flash + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + tools: + mode: code + persona: | + You are a coding assistant powered by the {{model}} model. Your working + directory is {{cwd}}. + + Verify your work by running the code or tests. Keep answers brief and + factual. + - insert: + - id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index bde4f4dbb9..fbc6af65b4 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -69,18 +69,36 @@ interface Scenario { * Whether THIS scenario's fixtures keep the full request-header content (the * composed system prompt and tool schema list on `request/header` / * `request/header-delta` events) and compare it verbatim. Exactly one - * scenario pins it; every other scenario stores and compares that content as + * scenario pins it PER HEADER CLASS ({@link headerClass}); every other + * scenario of that class stores and compares that content as * `{{system}}`/`{{tools}}` tokens ({@link scrubRequestHeaders}), so a system - * prompt or tool-schema change shows up as ONE committed-fixture diff, not - * one per scenario. One pin suffices because header composition is - * suite-uniform (parent, spawn child, and fork child all compose the same - * prompt-modulo-cwd and the same tools) — and that premise is ASSERTED, not - * assumed: every non-pinning run's live headers must equal the pinned - * fixture's (normalized), so a session-dependent header (say, a restricted - * subagent toolset) fails loud until it gets its own pinning scenario. + * prompt or tool-schema change shows up as ONE committed-fixture diff per + * class, not one per scenario. One pin per class suffices because header + * composition is class-uniform (parent, spawn child, and fork child all + * compose the same prompt-modulo-cwd and the same tools) — and that premise + * is ASSERTED, not assumed: every non-pinning run's live headers must equal + * its class's pinned fixture's (normalized), so a session-dependent header + * (say, a restricted subagent toolset) fails loud until it gets its own + * pinning scenario. * Defaults to false. */ pinsHeader?: boolean + /** + * Which header-composition class this scenario belongs to. Scenarios that + * boot the same config compose the same header; each class has exactly one + * {@link pinsHeader} scenario, and the uniformity guard compares every + * other member against ITS class's pin. Defaults to `'default'` (the + * example's stock `cordis.yml`); the Code Mode scenarios — booting overlay + * configs whose tool list and prompt sections differ by construction — + * carry their own classes. + */ + headerClass?: string + /** + * Alternate live-config basename under `examples/acp-agent/` for this + * scenario's boot (the replay swap derives `*cordis.snapshot.yml` from it). + * Defaults to `cordis.yml`. + */ + configBase?: string } const SCENARIOS: Scenario[] = [ @@ -146,11 +164,28 @@ const SCENARIOS: Scenario[] = [ { name: 'hook-codex-posttool-block', hasModelTurn: true, recorded: true }, { name: 'hook-codex-posttool-context', hasModelTurn: true, recorded: true }, { name: 'hook-codex-stop-continue', hasModelTurn: true, recorded: true }, + // Code Mode: the registry in `mode: code` — the wire tool list collapses to + // [run_code], the tools:sdk section rides in the prompt, and the program's + // tool calls land as tool/code-dispatch events. Each mode boots its own + // overlay config, composes a different header by construction, and + // therefore pins its own class. + { name: 'code-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'code', configBase: 'code-mode.cordis.yml' }, + { name: 'both-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'both', configBase: 'both-mode.cordis.yml' }, ] -/** The single header-pinning scenario. Guarded here (and by a meta-test) so the pin cannot silently vanish. */ -const pinningScenario = SCENARIOS.find(s => s.pinsHeader === true) -if (pinningScenario === undefined) throw new Error('acp.snapshot: no scenario pins the request-header content') +/** Each header class's single pinning scenario. Guarded here (and by a meta-test) so a pin cannot silently vanish. */ +const pinningByClass = new Map() +for (const scenario of SCENARIOS) { + if (scenario.pinsHeader !== true) continue + const cls = scenario.headerClass ?? 'default' + const existing = pinningByClass.get(cls) + if (existing) throw new Error(`acp.snapshot: header class "${cls}" pinned by both ${existing.name} and ${scenario.name}`) + pinningByClass.set(cls, scenario) +} +for (const scenario of SCENARIOS) { + const cls = scenario.headerClass ?? 'default' + if (!pinningByClass.has(cls)) throw new Error(`acp.snapshot: no scenario pins the request-header content of class "${cls}" (needed by ${scenario.name})`) +} /** The sibling child-fixture paths for a scenario (`session.1.jsonl` …). */ function childFixturePaths(dir: string, childSessions: number): string[] { @@ -221,6 +256,11 @@ for (const scenario of SCENARIOS) { // replays from its own script. In RECORD they are harvested, not read. ...!RECORDING && childSessions > 0 ? { childFiles: childFixturePaths(dir, childSessions) } : {}, ...existsSync(workspaceDir) ? { workspaceDir } : {}, + // A scenario booting an overlay tree passes its live config; the bin's + // replay swap derives the sibling `*cordis.snapshot.yml` from it. + ...scenario.configBase !== undefined + ? { configPath: join(SNAPSHOTS_DIR, '..', '..', scenario.configBase) } + : {}, }) // Scrub every volatile id the run produced: the ACP server-issued session @@ -281,19 +321,20 @@ for (const scenario of SCENARIOS) { } } - // Header-uniformity guard: the single pin is sound only while every - // session in the suite composes the SAME header and keeps it for the - // whole run. Assert both halves live. (1) Every request/header the run - // produced (parent, spawn child, fork child, initial or resume) must - // equal the pinned fixture's header after each side is normalized - // against its own volatile values. (2) No request/header-delta may - // appear at all — a mid-run header change diverges from the pin by - // construction, and its content would be invisible under the scrub. If - // either fails, either the header changed (update the pin: re-record or - // hand-edit the pinning scenario's fixture) or composition became - // session-dependent by design (give the divergent shape its own - // pinning scenario). + // Header-uniformity guard: a class's single pin is sound only while + // every session in that class composes the SAME header and keeps it for + // the whole run. Assert both halves live. (1) Every request/header the + // run produced (parent, spawn child, fork child, initial or resume) + // must equal the CLASS's pinned fixture's header after each side is + // normalized against its own volatile values. (2) No + // request/header-delta may appear at all — a mid-run header change + // diverges from the pin by construction, and its content would be + // invisible under the scrub. If either fails, either the header changed + // (update the pin: re-record or hand-edit the pinning scenario's + // fixture) or composition became session-dependent by design (give the + // divergent shape its own pinning scenario and class). if (scenario.pinsHeader !== true) { + const pinningScenario = pinningByClass.get(scenario.headerClass ?? 'default')! const pinnedFixture = await readFile(join(SNAPSHOTS_DIR, pinningScenario.name, 'session.jsonl'), 'utf8') const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture)) expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`) @@ -350,10 +391,21 @@ describe('snapshot fixtures', () => { } }) - it('exactly one scenario pins the request-header content', () => { - // Zero pins would drop the prompt/schema surface from the suite entirely; - // two would split it. The single pin is the design (pinned-header RFC). - expect(SCENARIOS.filter(s => s.pinsHeader === true).map(s => s.name)).toEqual(['text-turn']) + it('exactly one scenario pins the request-header content of each header class', () => { + // Zero pins would drop a class's prompt/schema surface from the suite + // entirely; two would split it. One pin per class is the design + // (pinned-header RFC; the Code Mode classes compose different headers by + // construction, so each carries its own pin). + const pins = new Map() + for (const scenario of SCENARIOS.filter(s => s.pinsHeader === true)) { + const cls = scenario.headerClass ?? 'default' + pins.set(cls, [...pins.get(cls) ?? [], scenario.name]) + } + expect(Object.fromEntries(pins)).toEqual({ + 'default': ['text-turn'], + 'code': ['code-mode-turn'], + 'both': ['both-mode-turn'], + }) }) it('committed fixtures carry request-header content ONLY in the pinning scenario', async () => { diff --git a/examples/acp-agent/tests/snapshot-harness.ts b/examples/acp-agent/tests/snapshot-harness.ts index 8285b870bf..7b04b81e23 100644 --- a/examples/acp-agent/tests/snapshot-harness.ts +++ b/examples/acp-agent/tests/snapshot-harness.ts @@ -124,6 +124,14 @@ interface RunOptions { * start from an empty workspace. */ workspaceDir?: string + /** + * Alternate LIVE config path for the boot (absolute). Defaults to the + * example's `cordis.yml`. A scenario needing a differently-composed tree + * (the Code Mode scenarios) ships an overlay whose basename still ends in + * `cordis.yml`, so the bin's replay swap resolves the sibling + * `*cordis.snapshot.yml` the same way it does for the default. + */ + configPath?: string } /** @@ -163,7 +171,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise child = spawn( process.execPath, - ['--import', tsxLoader, binScript, configPath], + ['--import', tsxLoader, binScript, opts.configPath ?? configPath], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] }, ) diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/input.json b/examples/acp-agent/tests/snapshots/both-mode-turn/input.json new file mode 100644 index 0000000000..699e4a2043 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl new file mode 100644 index 0000000000..a2b0e9921b --- /dev/null +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl @@ -0,0 +1,110 @@ +{"type":"session","version":0,"id":"55c51419-0ee3-4c06-8199-cc69eef57a45","createdAt":1783484575071,"cwd":"/tmp/acp-snap-cwd-lORmOD"} +{"type":"turn/start","seq":0,"time":1783484575075,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783484575076,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783484575078,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783484575079,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-lORmOD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783484575489,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783484575489,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783484575561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783484575587,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783484575587,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783484575588,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783484575588,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} +{"type":"assistant/chunk","seq":11,"time":1783484575588,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":12,"time":1783484575613,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":13,"time":1783484575614,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":14,"time":1783484575614,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":15,"time":1783484575614,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":16,"time":1783484575639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":17,"time":1783484575639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" runs"}}} +{"type":"assistant/chunk","seq":18,"time":1783484575639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":19,"time":1783484575662,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":20,"time":1783484575663,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} +{"type":"assistant/chunk","seq":21,"time":1783484575663,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":22,"time":1783484575663,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":23,"time":1783484575688,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":24,"time":1783484575688,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" via"}}} +{"type":"assistant/chunk","seq":25,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} +{"type":"assistant/chunk","seq":26,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} +{"type":"assistant/chunk","seq":27,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} +{"type":"assistant/chunk","seq":28,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":29,"time":1783484575713,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} +{"type":"assistant/chunk","seq":30,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":31,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":32,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":33,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":34,"time":1783484575739,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":35,"time":1783484575739,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}} +{"type":"assistant/chunk","seq":36,"time":1783484575739,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":37,"time":1783484575740,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":38,"time":1783484575815,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":39,"time":1783484575815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":40,"time":1783484575840,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":41,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":42,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":43,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":44,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":45,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":46,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":47,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":48,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":49,"time":1783484575890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":50,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":51,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":52,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":53,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":54,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":55,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":56,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":57,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":58,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":59,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":60,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":61,"time":1783484575942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":62,"time":1783484575942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":63,"time":1783484575942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":64,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":65,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":66,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":67,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":68,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":69,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" }"}}} +{"type":"assistant/chunk","seq":70,"time":1783484576019,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":");"}}} +{"type":"assistant/chunk","seq":71,"time":1783484576019,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":72,"time":1783484576044,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":73,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns the output. Let me do that."}}}} +{"type":"assistant/chunk","seq":74,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","arguments":"{\"code\": \"return await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\"}"}}}} +{"type":"assistant/chunk","seq":75,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3733,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":33}}}} +{"type":"assistant/chunk","seq":76,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":77,"time":1783484576078,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns the output. Let me do that."},{"type":"tool-call","id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","arguments":"{\"code\": \"return await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\"}"}],"usage":{"inputTokens":3733,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":33}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76],"surfaceOp":"append"} +{"type":"tool/call","seq":78,"time":1783484576078,"data":{"turn":1,"step":1,"callId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","arguments":"{\"code\": \"return await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\"}"}} +{"type":"tool/code-dispatch","seq":79,"time":1783484576205,"data":{"parentCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","subCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK"},"isError":false,"resultSummary":"BOTH_OK\n"}} +{"type":"tool/result","seq":80,"time":1783484576208,"data":{"turn":1,"step":1,"callId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[78],"surfaceOp":"append"} +{"type":"step/end","seq":81,"time":1783484576208,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":82,"time":1783484576209,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":83,"time":1783484576645,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":84,"time":1783484576645,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":85,"time":1783484576758,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":86,"time":1783484576782,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":87,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":88,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} +{"type":"assistant/chunk","seq":89,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":90,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":91,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":92,"time":1783484576810,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":93,"time":1783484576835,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":94,"time":1783484576836,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":95,"time":1783484576836,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":96,"time":1783484576836,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":97,"time":1783484576860,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":98,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":99,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} +{"type":"assistant/chunk","seq":100,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} +{"type":"assistant/chunk","seq":101,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} +{"type":"assistant/chunk","seq":102,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is \"BOTH_OK\". Let me reply with that."}}}} +{"type":"assistant/chunk","seq":103,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} +{"type":"assistant/chunk","seq":104,"time":1783484576895,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":138,"outputTokens":18,"cacheReadTokens":3712,"reasoningTokens":14}}}} +{"type":"assistant/chunk","seq":105,"time":1783484576895,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":106,"time":1783484576895,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is \"BOTH_OK\". Let me reply with that."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":138,"outputTokens":18,"cacheReadTokens":3712,"reasoningTokens":14}},"sourceEventSeqs":[83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105],"surfaceOp":"append"} +{"type":"step/end","seq":107,"time":1783484576895,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":108,"time":1783484576895,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl new file mode 100644 index 0000000000..d307e1d60f --- /dev/null +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl @@ -0,0 +1,55 @@ +{"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}}"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" call"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" runs"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" B"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OTH"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" via"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".b"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" do"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","title":"Run code","kind":"execute","status":"in_progress","rawInput":"return await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","status":"completed","content":[{"type":"content","content":{"type":"text","text":"BOTH_OK\n"}}],"title":"Run code (1 tool call)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"B"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OTH"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"B"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"OTH"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_OK"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/input.json b/examples/acp-agent/tests/snapshots/code-mode-turn/input.json new file mode 100644 index 0000000000..c6d4a1039e --- /dev/null +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl new file mode 100644 index 0000000000..dd9c0bed28 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl @@ -0,0 +1,196 @@ +{"type":"session","version":0,"id":"92c80cd8-dddc-4cd6-a05a-9676ef54af5e","createdAt":1783484558135,"cwd":"/tmp/acp-snap-cwd-zej9wx"} +{"type":"turn/start","seq":0,"time":1783484558139,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783484558139,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783484558142,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783484558142,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-zej9wx.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783484558789,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783484558789,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783484558877,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783484558904,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783484558905,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783484558905,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783484558905,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":11,"time":1783484558933,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":12,"time":1783484558933,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":13,"time":1783484558934,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":14,"time":1783484558934,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":15,"time":1783484558934,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":16,"time":1783484558957,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":17,"time":1783484558957,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}} +{"type":"assistant/chunk","seq":18,"time":1783484558958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}} +{"type":"assistant/chunk","seq":19,"time":1783484558958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":20,"time":1783484558958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} +{"type":"assistant/chunk","seq":21,"time":1783484558982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} +{"type":"assistant/chunk","seq":22,"time":1783484558982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":23,"time":1783484558982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":24,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":25,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":26,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":27,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":28,"time":1783484559035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} +{"type":"assistant/chunk","seq":29,"time":1783484559035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}} +{"type":"assistant/chunk","seq":30,"time":1783484559035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":31,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} +{"type":"assistant/chunk","seq":32,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} +{"type":"assistant/chunk","seq":33,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":34,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":35,"time":1783484559060,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":36,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":37,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":38,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":39,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} +{"type":"assistant/chunk","seq":40,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}} +{"type":"assistant/chunk","seq":41,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":42,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Returns"}}} +{"type":"assistant/chunk","seq":43,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":44,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} +{"type":"assistant/chunk","seq":45,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} +{"type":"assistant/chunk","seq":46,"time":1783484559089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} +{"type":"assistant/chunk","seq":47,"time":1783484559114,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":48,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":49,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} +{"type":"assistant/chunk","seq":50,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} +{"type":"assistant/chunk","seq":51,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}} +{"type":"assistant/chunk","seq":52,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Then"}}} +{"type":"assistant/chunk","seq":53,"time":1783484559186,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":54,"time":1783484559187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":55,"time":1783484559187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}} +{"type":"assistant/chunk","seq":56,"time":1783484559201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":57,"time":1783484559201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} +{"type":"assistant/chunk","seq":58,"time":1783484559201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} +{"type":"assistant/chunk","seq":59,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}} +{"type":"assistant/chunk","seq":60,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} +{"type":"assistant/chunk","seq":61,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":62,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":63,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":64,"time":1783484559251,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" code"}}} +{"type":"assistant/chunk","seq":65,"time":1783484559252,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":66,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":67,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":68,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":69,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":70,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":71,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":72,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":73,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":74,"time":1783484559382,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":75,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":76,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":77,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":78,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":79,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":80,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":81,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":82,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":83,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":84,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":85,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":86,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":87,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":88,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":89,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":90,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":91,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":92,"time":1783484559461,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":93,"time":1783484559461,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":94,"time":1783484559461,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":95,"time":1783484559489,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":96,"time":1783484559489,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":97,"time":1783484559489,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":98,"time":1783484559515,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":99,"time":1783484559515,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":100,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":101,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":102,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":103,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":104,"time":1783484559541,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":105,"time":1783484559541,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":106,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":107,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":108,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":109,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":110,"time":1783484559566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":111,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":112,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":113,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":114,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":115,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":116,"time":1783484559592,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":117,"time":1783484559592,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":118,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":119,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":120,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":121,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":122,"time":1783484559617,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":123,"time":1783484559617,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":124,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":125,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":126,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":127,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":128,"time":1783484559643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":129,"time":1783484559644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":130,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":131,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":132,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"()"}}} +{"type":"assistant/chunk","seq":133,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":134,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\"+"}}} +{"type":"assistant/chunk","seq":135,"time":1783484559697,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":136,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":137,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":138,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":139,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":140,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"();"}}} +{"type":"assistant/chunk","seq":141,"time":1783484559724,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":142,"time":1783484559725,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":143,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash with `echo CODE_ONE`\n2. Calls bash with `echo CODE_TWO`\n3. Returns the two outputs joined with a plus sign\n\nThen reply with just that joined string.\n\nLet me write the code."}}}} +{"type":"assistant/chunk","seq":144,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}} +{"type":"assistant/chunk","seq":145,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2121,"outputTokens":171,"cacheReadTokens":0,"reasoningTokens":61}}}} +{"type":"assistant/chunk","seq":146,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":147,"time":1783484559780,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash with `echo CODE_ONE`\n2. Calls bash with `echo CODE_TWO`\n3. Returns the two outputs joined with a plus sign\n\nThen reply with just that joined string.\n\nLet me write the code."},{"type":"tool-call","id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"usage":{"inputTokens":2121,"outputTokens":171,"cacheReadTokens":0,"reasoningTokens":61}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146],"surfaceOp":"append"} +{"type":"tool/call","seq":148,"time":1783484559780,"data":{"turn":1,"step":1,"callId":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}} +{"type":"tool/code-dispatch","seq":149,"time":1783484559896,"data":{"parentCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","subCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo CODE_ONE"},"isError":false,"resultSummary":"CODE_ONE\n"}} +{"type":"tool/code-dispatch","seq":150,"time":1783484559908,"data":{"parentCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","subCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo CODE_TWO"},"isError":false,"resultSummary":"CODE_TWO\n"}} +{"type":"tool/result","seq":151,"time":1783484559913,"data":{"turn":1,"step":1,"callId":"call_00_TBMd5LxIFwxqRBHOErfg0279","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[148],"surfaceOp":"append"} +{"type":"step/end","seq":152,"time":1783484559913,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":153,"time":1783484559914,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":154,"time":1783484560545,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":155,"time":1783484560545,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":156,"time":1783484560716,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" result"}}} +{"type":"assistant/chunk","seq":157,"time":1783484560744,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":158,"time":1783484560744,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":159,"time":1783484560769,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} +{"type":"assistant/chunk","seq":160,"time":1783484560770,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} +{"type":"assistant/chunk","seq":161,"time":1783484560795,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} +{"type":"assistant/chunk","seq":162,"time":1783484560822,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} +{"type":"assistant/chunk","seq":163,"time":1783484560823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":164,"time":1783484560823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":165,"time":1783484560823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":166,"time":1783484560847,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":167,"time":1783484560847,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} +{"type":"assistant/chunk","seq":168,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":169,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":170,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":171,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"`."}}} +{"type":"assistant/chunk","seq":172,"time":1783484560872,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":173,"time":1783484560872,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"'ll"}}} +{"type":"assistant/chunk","seq":174,"time":1783484560898,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":175,"time":1783484560898,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":176,"time":1783484560898,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}} +{"type":"assistant/chunk","seq":177,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":178,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} +{"type":"assistant/chunk","seq":179,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":180,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":181,"time":1783484560925,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":182,"time":1783484560925,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} +{"type":"assistant/chunk","seq":183,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":184,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} +{"type":"assistant/chunk","seq":185,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":186,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} +{"type":"assistant/chunk","seq":187,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} +{"type":"assistant/chunk","seq":188,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The result is exactly what was requested: `CODE_ONE+CODE_TWO`. I'll reply with just that string."}}}} +{"type":"assistant/chunk","seq":189,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} +{"type":"assistant/chunk","seq":190,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":135,"outputTokens":33,"cacheReadTokens":2176,"reasoningTokens":25}}}} +{"type":"assistant/chunk","seq":191,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":192,"time":1783484560951,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The result is exactly what was requested: `CODE_ONE+CODE_TWO`. I'll reply with just that string."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":135,"outputTokens":33,"cacheReadTokens":2176,"reasoningTokens":25}},"sourceEventSeqs":[154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191],"surfaceOp":"append"} +{"type":"step/end","seq":193,"time":1783484560951,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":194,"time":1783484560951,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl new file mode 100644 index 0000000000..3660515e4c --- /dev/null +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl @@ -0,0 +1,98 @@ +{"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}}"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Returns"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" outputs"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" plus"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sign"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Then"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","status":"completed","content":[{"type":"content","content":{"type":"text","text":"CODE_ONE+CODE_TWO"}}],"title":"Run code (2 tool calls)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" result"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" was"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" requested"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"+"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'ll"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"+"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_T"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"WO"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/code-agent/README.md b/examples/code-agent/README.md new file mode 100644 index 0000000000..9b6619c0b3 --- /dev/null +++ b/examples/code-agent/README.md @@ -0,0 +1,17 @@ +# code-agent — the Code Mode demo + +The [Code Mode](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) form of the coding agent: instead of one native tool call per step, the model is offered exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK section declaring every other registered tool (`bash`, `read`, `write`, `edit`, `todo_write`). The model composes tools by writing a program; the program runs in a fresh worker thread (`@deepseek-ai/dsh-code-runtime-worker`), its tool calls bridge back through the ordinary `tools/pre-execute`/`post-execute` pipeline one at a time, each is logged as a `tool/code-dispatch` session event, and ONLY what the program prints or returns re-enters the model's context. + +```sh +pnpm run demo:code # needs DEEPSEEK_API_KEY (repo-root .env works) +``` + +Try a task that spans several tool calls, e.g.: + +> Count the lines of every `*.md` file under docs/ and write the three largest to summary.txt. + +and watch the transcript: one `run_code` call, a program looping over tools, and a result the model curated instead of five round-trips of raw tool output. + +Two lines of `cordis.yml` make the difference from [examples/coding-agent](../coding-agent/README.md): the `code-runtime` entry (the worker-thread backend registering `ctx.codeRuntime`) and `tools: { mode: code }` on the app (flip it to `both` to offer native calls AND `run_code` side by side; remove both lines and it IS the coding agent). + +Tests: `tests/keyless-smoke.e2e.ts` boots the real `cordis.yml` through the Loader with no prompt (the export-shape guard); `tests/code-mode.e2e.ts` is the with-key proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed, and the curated answer came back. diff --git a/examples/code-agent/cordis.yml b/examples/code-agent/cordis.yml new file mode 100644 index 0000000000..e4bb4de1e5 --- /dev/null +++ b/examples/code-agent/cordis.yml @@ -0,0 +1,84 @@ +# The code-agent plugin tree: the Code Mode demo. The same spine as +# examples/coding-agent — the DeepSeek adapter, local bash, filesystem and +# todo tool stacks over the stdio chat app — with TWO differences that turn +# it into Cloudflare-style Code Mode: +# +# 1. `code-runtime` loads the worker-thread code-execution backend +# (`ctx.codeRuntime`): one fresh Node worker per run, TypeScript in. +# 2. `stdio-agent` sets `tools: { mode: code }`, so the model is offered +# exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK +# prompt section declaring bash/read/write/edit/todo_write; the model +# composes them by WRITING A PROGRAM, and only what it prints or +# returns re-enters its context. +# +# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the +# environment — the dsh-stdio-agent bin loads the gitignored repo-root .env +# first. cordis.yml reads them via the `!!js` tag. + +# Hot-module reload for the dev/demo loop (needs `node --expose-internals`). +- id: hmr + name: '@cordisjs/plugin-hmr' + config: + root: ['.'] + +# The DeepSeek adapter. +- id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + config: + apiKey: !!js process.env.DEEPSEEK_API_KEY + baseURL: !!js process.env.DEEPSEEK_BASE_URL + models: + - deepseek-v4-pro + - deepseek-v4-flash + +# Local bash executor for the spine's `bash` tool schemas. +- id: bash + name: '@deepseek-ai/dsh-bash-local' + config: + timeoutMs: 60000 + +# The code-execution backend: `run_code` programs execute here, in one fresh +# worker thread per run with an empty environment, port-bridged tool +# bindings, and busy-time/wall-clock/heap caps (all overridable here). +- id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' + +# The stdio chat app with the registry flipped to Code Mode: the wire tool +# list collapses to [run_code] and the `tools:sdk` prompt section carries the +# generated TypeScript declarations for every other registered tool. +- id: stdio-agent + name: '@deepseek-ai/dsh-stdio-agent' + config: + model: deepseek-v4-flash + tools: + mode: code + # Set RESUME_SESSION_ID to continue a prior persisted session (the ids + # live under ./.sessions); unset starts a fresh session each run. + resumeSessionId: !!js process.env.RESUME_SESSION_ID + persistenceRoot: './.sessions' + welcome: 'code-mode agent ready. Give it a multi-tool task.' + persona: | + You are code-agent, a coding assistant powered by the {{model}} model. + + You work by writing TypeScript programs for run_code: batch related + tool work into one program, loop and branch where it helps, and print + or return ONLY the findings that matter. + +# The model-facing todo_write tool: whole-list task tracking written to the +# session log (todo/write), rendered as a stdio checklist. +- id: tool-todo + name: '@deepseek-ai/dsh-tool-todo' + +# Filesystem capability stack: local provider, read-before-write/edit policy +# gate, then the model-facing read/write/edit tools — all reachable from a +# run_code program as `tools.read(...)` / `tools.write(...)` / `tools.edit(...)`. +- id: fs-local + name: '@deepseek-ai/dsh-fs-local' + config: + cwd: !!js process.cwd() + +- id: fs-policy + name: '@deepseek-ai/dsh-fs-policy' + +- id: tool-fs + name: '@deepseek-ai/dsh-tool-fs' diff --git a/examples/code-agent/package.json b/examples/code-agent/package.json new file mode 100644 index 0000000000..0aa0e52c52 --- /dev/null +++ b/examples/code-agent/package.json @@ -0,0 +1,7 @@ +{ + "name": "code-agent-example", + "private": true, + "version": "0.0.1", + "type": "module", + "description": "Runnable demo: Code Mode — the model writes TypeScript against the tool registry" +} diff --git a/examples/code-agent/tests/code-mode.e2e.ts b/examples/code-agent/tests/code-mode.e2e.ts new file mode 100644 index 0000000000..6b0771380d --- /dev/null +++ b/examples/code-agent/tests/code-mode.e2e.ts @@ -0,0 +1,115 @@ +import { mkdtemp, readFile, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry, { RUN_CODE_NAME } from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' +import * as ToolBash from '@deepseek-ai/dsh-tool-bash' +import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' +import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker' + +/** + * The Code Mode with-key proof (the RFC's e2e tier): a REAL model under + * `mode: 'code'`, a task that requires composing two tool calls, verified + * against the WORLD — the persisted request header carried exactly + * `[run_code]` as the wire tool list, each sub-call landed as a + * `tool/code-dispatch` event, the file the program wrote exists on disk, and + * the final answer is the program's curated output. Key-gated (see + * vitest.e2e.config.ts); the keyless Loader-path smoke lives in + * `keyless-smoke.e2e.ts`. + */ + +const PERSONA = 'You are code-agent. You work by writing TypeScript programs for run_code: ' + + 'batch related tool work into one program and print or return ONLY the findings that matter.' + +let ctx: Context | undefined +let workdir: string | undefined + +afterEach(async () => { + // Always dispose, even on failure/retry/timeout: agent-loop teardown stops + // the loop, the executor kills stray processes, and the code runtime's + // dispose awaits worker exits. + await ctx?.fiber.dispose() + ctx = undefined + if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) + workdir = undefined +}) + +async function codeModeHarness(cwd: string): Promise { + const harness = new Context() + await harness.plugin(LlmService) + await harness.plugin(SessionStore) + await harness.plugin(SystemPrompt, { persona: PERSONA }) + await harness.plugin(ToolRegistry, { mode: 'code' }) + await harness.plugin(AgentRegistry) + await harness.plugin(AgentLoop, { agents: [] }) + await harness.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] }) + await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 }) + await harness.plugin(ToolBash) + await harness.plugin(WorkerCodeRuntime, {}) + return harness +} + +function waitForIdle(harness: Context, agent: ReactLoopAgent): Promise { + return new Promise((resolve) => { + const dispose = harness.on('agent/status', (subject, status) => { + if (subject === agent && status === 'idle') { + dispose() + resolve() + } + }) + }) +} + +describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a program over real tools', () => { + it('collapses the wire tool list to [run_code], bridges sub-calls, and returns curated output', async () => { + workdir = await mkdtemp(join(tmpdir(), 'dsh-code-mode-e2e-')) + ctx = await codeModeHarness(workdir) + const agent = ctx.agentLoop.create(AgentId('e2e-code-mode'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Using one run_code program: run `echo alpha-7` with the bash tool, run `echo beta-9` with the bash tool, ' + + 'then write both outputs joined by a plus sign into combined.txt (bash heredoc or redirect), ' + + 'and return only the joined string.', + }]) + await waitForIdle(ctx, agent) + const events: SessionEvent[] = [...agent.session.events] + + // The wire contract: every request this session made offered EXACTLY ONE + // tool — run_code (the logged header snapshots the assembled list). + const headers = events.filter(event => event.type === 'request/header') + expect(headers.length).toBeGreaterThan(0) + for (const header of headers) { + expect(header.data.header.tools?.map(tool => tool.name)).toEqual([RUN_CODE_NAME]) + } + // The model actually went through run_code… + const calls = events.filter(event => event.type === 'tool/call') + expect(calls.length).toBeGreaterThan(0) + expect(calls.every(event => event.data.name === RUN_CODE_NAME)).toBe(true) + // …and the program's tool calls landed as dispatch events under it. + const dispatches = events.filter(event => event.type === 'tool/code-dispatch') + expect(dispatches.length).toBeGreaterThanOrEqual(2) + expect(dispatches.every(event => event.data.name === 'bash')).toBe(true) + const parents = new Set(calls.map(event => event.data.callId)) + expect(dispatches.every(event => parents.has(event.data.parentCallId))).toBe(true) + + // World verification: the file the program wrote, and the curated answer. + const combined = await readFile(join(workdir, 'combined.txt'), 'utf8') + expect(combined).toContain('alpha-7') + expect(combined).toContain('beta-9') + const finalMessage = events.findLast(event => event.type === 'assistant/message') + const finalText = finalMessage !== undefined + ? finalMessage.data.content.filter(block => block.type === 'text').map(block => block.text).join('') + : '' + expect(finalText).toContain('alpha-7') + expect(finalText).toContain('beta-9') + }, 180_000) +}) diff --git a/examples/code-agent/tests/keyless-smoke.e2e.ts b/examples/code-agent/tests/keyless-smoke.e2e.ts new file mode 100644 index 0000000000..4b7a150e99 --- /dev/null +++ b/examples/code-agent/tests/keyless-smoke.e2e.ts @@ -0,0 +1,90 @@ +import { spawn, type ChildProcessWithoutNullStreams } 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' +import { afterEach, describe, expect, it } from 'vitest' + +/** + * Keyless Loader-path smoke for examples/code-agent: boot the REAL example + * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` + * (the cordis Loader, `unwrapExports`, the full plugin tree incl. the + * worker-thread code runtime and the registry in `mode: code`), then close + * stdin with no prompt and assert the ready banner + a clean exit. + * + * No prompt is ever sent, so the model is NEVER called and no `run_code` + * turn happens — a dummy key lets `llm-deepseek`'s key-PRESENT check boot + * the tree. This is the export-shape guard (postmortem 0001) for the Code + * Mode composition; the with-key proof lives in `code-mode.e2e.ts`. + */ + +const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url)) +const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig +// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside +// the repo, so point it at the repo tsconfig. +const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) + +let child: ChildProcessWithoutNullStreams | undefined +let workdir: string | undefined + +afterEach(async () => { + if (child !== undefined && child.exitCode === null) child.kill('SIGKILL') + child = undefined + if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) + workdir = undefined +}) + +async function bootAndEof(): Promise<{ stdout: string; code: number }> { + workdir = await mkdtemp(join(tmpdir(), 'code-agent-smoke-')) + const cwd = workdir + return new Promise((resolve, reject) => { + const proc = spawn( + process.execPath, + // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:code). + ['--expose-internals', '--import', tsxLoader, binScript, configPath], + { + cwd, + env: { + ...process.env, + TSX_TSCONFIG_PATH: repoTsconfig, + // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots. + // No prompt is sent, so the adapter never streams — no network call. + DEEPSEEK_API_KEY: 'keyless-smoke-no-call', + }, + stdio: ['pipe', 'pipe', 'pipe'], + }, + ) + child = proc + let stdout = '' + let stderr = '' + proc.stdout.setEncoding('utf8') + proc.stdout.on('data', (chunk: string) => { stdout += chunk }) + proc.stderr.setEncoding('utf8') + proc.stderr.on('data', (chunk: string) => { stderr += chunk }) + + const timer = setTimeout(() => { + proc.kill('SIGKILL') + reject(new Error(`code-agent did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`)) + }, 10_000) + + proc.on('exit', (code) => { + clearTimeout(timer) + if (code === 0) resolve({ stdout, code }) + else reject(new Error(`code-agent exited ${code}. stderr:\n${stderr}`)) + }) + proc.on('error', (err) => { clearTimeout(timer); reject(err) }) + + // No prompt — just EOF, so the stdio UI exits without ever running a turn. + proc.stdin.end() + }) +} + +describe('code-agent keyless smoke (real cordis.yml via the Loader)', () => { + it('boots the Code Mode plugin tree, prints its banner, and exits cleanly on EOF', async () => { + const { stdout, code } = await bootAndEof() + expect(code).toBe(0) + expect(stdout).toContain('code-mode agent ready.') + }, 15_000) +}) diff --git a/package.json b/package.json index bba471ea5f..4fce3dad57 100644 --- a/package.json +++ b/package.json @@ -63,6 +63,7 @@ "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", + "demo:code": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/code-agent/cordis.yml", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md index b98baa43e6..a4ab8956be 100644 --- a/packages/code-runtime/README.md +++ b/packages/code-runtime/README.md @@ -1,6 +1,6 @@ # code-runtime/ — code-execution capability family -The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's Code Mode, specified alongside the seam in the [Code Mode RFC](../../docs/rfc/proposed/feature/2026-06-15-code-mode.md). **Product** packages. +The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the generated TypeScript SDK); design in the [Code Mode RFC](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md). **Product** packages. | Package | Role | ctx key | |---|---|---| diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md index b8f440397a..f691904e88 100644 --- a/packages/code-runtime/code-runtime-worker/README.md +++ b/packages/code-runtime/code-runtime-worker/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-code-runtime-worker -Worker-thread implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam: `WorkerCodeRuntime` runs each program in ONE fresh Node `worker_threads.Worker` — TypeScript in, type-stripped host-side, bindings bridged over the message port, `{ value, logs, error? }` out. **Containment, not a security boundary**: trust posture is bash-equivalent by design (the [Code Mode RFC](../../../docs/rfc/proposed/feature/2026-06-15-code-mode.md) § Trust posture), with containment bash does not have — separate isolate, empty environment, heap cap, hard termination. +Worker-thread implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam: `WorkerCodeRuntime` runs each program in ONE fresh Node `worker_threads.Worker` — TypeScript in, type-stripped host-side, bindings bridged over the message port, `{ value, logs, error? }` out. **Containment, not a security boundary**: trust posture is bash-equivalent by design (the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) § Trust posture), with containment bash does not have — separate isolate, empty environment, heap cap, hard termination. ## Config diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md index 2d7b12add1..20c9274b9c 100644 --- a/packages/code-runtime/code-runtime/README.md +++ b/packages/code-runtime/code-runtime/README.md @@ -2,7 +2,7 @@ The **code-execution seam**: an abstract `CodeRuntime` service (`ctx.codeRuntime`) defining WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW. -This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode RFC](../../../docs/rfc/proposed/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer. +This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer. ## Service API (`ctx.codeRuntime`) diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts index af967da61d..5595469afe 100644 --- a/packages/code-runtime/code-runtime/src/index.ts +++ b/packages/code-runtime/code-runtime/src/index.ts @@ -7,7 +7,7 @@ * substrate (worker thread, separate process, container) and by source * language, both declared as readonly descriptors. The design and its * consumer (the tool registry's Code Mode) are specified in the Code Mode RFC - * (docs/rfc/proposed/feature/2026-06-15-code-mode.md). + * (docs/rfc/implemented/feature/2026-06-15-code-mode.md). * * The split mirrors the bash seam (`BashExecutor`): the runtime knows nothing * about tools or sessions — it is handed named async functions and a program, diff --git a/packages/core/agent-core/src/index.ts b/packages/core/agent-core/src/index.ts index 785c8d1ff2..a3221bdf8f 100644 --- a/packages/core/agent-core/src/index.ts +++ b/packages/core/agent-core/src/index.ts @@ -48,7 +48,7 @@ import z from 'schemastery' import LlmService from '@deepseek-ai/dsh-llm' import SessionStore from '@deepseek-ai/dsh-session' import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt' -import ToolRegistry from '@deepseek-ai/dsh-tools' +import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' import * as invariants from '@deepseek-ai/dsh-invariants' import * as toolBash from '@deepseek-ai/dsh-tool-bash' @@ -61,10 +61,12 @@ export const name = 'agent-core' * `agents` to the agent loop (an app that pre-creates no agents, like the ACP * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt * plugin (the deployment's persona section and the explicit model-facing tool - * order). Every field is optional INPUT here because each owner's schema - * supplies the default (`[]` / `''` / absent — lexicographic); the schema is - * the INTERSECTION of the owners' own schemas, so validation and defaulting - * can never drift from them. + * order), the `tools` object to the tool registry (its presentation `mode`). + * Every field is optional INPUT here because each owner's schema + * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the + * schema is the INTERSECTION of the owners' own schemas (the registry's + * nested under its `tools` key), so validation and defaulting can never + * drift from them. */ export interface Config { /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */ @@ -73,10 +75,12 @@ export interface Config { persona?: SystemPromptConfig['persona'] /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */ toolOrder?: SystemPromptConfig['toolOrder'] + /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */ + tools?: ToolsConfig } -/** Intersect the owners' schemas so validation + defaulting stay identical. */ -export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config]) as unknown as z +/** Intersect the owners' schemas so validation + defaulting stay identical (the registry's nested under `tools`). */ +export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config, z.object({ tools: ToolRegistry.Config })]) as unknown as z /** * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber; @@ -101,7 +105,7 @@ export function apply(ctx: Context, config: Config): void { persona: config.persona ?? '', ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, }) - ctx.plugin(ToolRegistry) + ctx.plugin(ToolRegistry, config.tools ?? {}) ctx.plugin(AgentRegistry) ctx.plugin(invariants) ctx.plugin(toolBash) diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index aea87ad76c..7525fb8fd6 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -1,9 +1,18 @@ # dsh-tools -Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the allow/deny gate) → core dispatch → `tools/post-execute` (inspect/replace the result, attach context). +Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the allow/deny gate) → core dispatch → `tools/post-execute` (inspect/replace the result, attach context). The registry also owns HOW its tools are presented to the model — its `mode` config selects native function calling, [Code Mode](#code-mode), or both. ## Service: `ToolRegistry` (ctx key: `tools`) +### Config + +```yaml +tools: + mode: native # native (default) | code | both +``` + +`native` contributes every registered tool as a wire function definition — the default, byte-for-byte the pre-config behavior. `code` contributes exactly ONE wire tool, `run_code`, plus the generated `tools:sdk` prompt section (see [Code Mode](#code-mode)). `both` contributes every native definition AND `run_code` + the SDK section. Non-native modes require a loaded `ctx.codeRuntime` with `language: 'typescript'`; a missing or mismatched runtime rejects every prompt assembly with an actionable error, and a `systemPrompt.toolOrder` naming tools the mode no longer contributes rejects the assembly the same way. + ### Public API - `ctx.tools.register(definition: ToolDefinition): () => void` Register a tool. Disposed with the calling fiber. @@ -116,6 +125,16 @@ const bash = defineTool({ }) ``` +### Code Mode + +Under `mode: code` (or `both`) the registry turns the tool surface into a programming API, per the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md): the model writes a TypeScript program (the body of an async function) and passes it to the ONE wire tool `run_code`; the program runs in `ctx.codeRuntime` (the [code-execution seam](../../code-runtime/README.md) — the shipped backend is a worker thread) with one async binding per registered tool (`await tools.bash({...})`), and ONLY what it prints or returns re-enters the model's context. + +- **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating, at each assembly, a `declare const tools: {...}` TypeScript declaration of every registered tool except `run_code` (exotic names via quoted keys), plus fixed usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). The codegen (`jsonSchemaToTs`, exported) is TOTAL: constructs outside the `defineTool` subset degrade to `unknown`, never throw. +- **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 the logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes the underlying `ctx.tools.execute()` calls one at a time in submission order — the tool contract carries no concurrency-safety metadata yet), gated by `tools/pre-execute`/`tools/post-execute` like any native call (a deny reaches the program as a binding rejection), and logged as one `tool/code-dispatch` session event (log-only: `deriveMessages()` never surfaces it) with the deterministic sub-id `:code:`. A failed sub-call REJECTS the program-side promise with the tool's error text — real code error handling, no bespoke envelope. A sub-call's `additionalContext` is deliberately DROPPED (no safe outlet mid-run without breaking tool-call/result adjacency; deferred until a real hook needs it through Code Mode). +- **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. + +The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free — under `code`, the assembled tool list is exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code` ([examples/code-agent](../../../examples/code-agent/README.md)). + ### What is NOT here (TODO) - **Tool shapes review** — when real tools land (e.g. a concurrency-safety hint for parallel execution); phase 1 executes tool calls sequentially. diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json index a6d3bbe0ca..f6425538b1 100644 --- a/packages/core/tools/package.json +++ b/packages/core/tools/package.json @@ -23,13 +23,20 @@ "license": "BSD-3-Clause", "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-code-runtime": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-session": "^0.0.1", "@deepseek-ai/dsh-system-prompt": "^0.0.1", "cordis": "^4.0.0-rc.6" }, + "dependencies": { + "schemastery": "^3.18.0" + }, "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-code-runtime": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "cordis": "^4.0.0-rc.6" } diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts new file mode 100644 index 0000000000..be3b7c91af --- /dev/null +++ b/packages/core/tools/src/code-mode.ts @@ -0,0 +1,280 @@ +/** + * Code Mode: the `run_code` tool and its dispatch bridge. The model writes a + * TypeScript program; the bridge hands it to `ctx.codeRuntime` with one + * async binding per registered tool, serializes every binding call through a + * per-run queue onto `ToolRegistry.execute()` (so `tools/pre-execute` / + * `tools/post-execute` gate sub-calls exactly like native ones), logs each + * sub-dispatch as a `tool/code-dispatch` session event, and returns only the + * program's curated output. The registry itself decides WHEN this tool + * exists (its `mode` config); this module owns only the tool and the bridge. + * + * @module @deepseek-ai/dsh-tools/src/code-mode + */ + +import { inspect } from 'node:util' +import { CallId, HarnessError } from '@deepseek-ai/dsh-llm' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { CodeBindingFunction, CodeRunResult, CodeRuntime } from '@deepseek-ai/dsh-code-runtime' +import type {} from '@deepseek-ai/dsh-session' +import { defineTool } from './schema.ts' +import type { ToolDefinition, ToolRegistry } from './index.ts' + +declare module '@deepseek-ai/dsh-session' { + interface SessionEventMap { + /** + * 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. + * 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 } + } +} + +/** The model-facing name of the Code Mode tool. */ +export const RUN_CODE_NAME = 'run_code' + +/** The `tools:sdk` section order: inside the 100–199 tool-guidance band, after per-tool guidance sections. */ +export const SDK_SECTION_ORDER = 150 + +/** + * Thrown by `run_code` when the program run itself failed — a program + * exception, a budget expiry, an abort, or substrate death. Extends + * {@link HarnessError} (`code: 'CODE_RUN_FAILED'`); the registry's execution + * pipeline converts it into a structured `isError` result whose text carries + * the failure kind plus the captured logs, so the model can self-correct. + */ +export class CodeRunFailedError extends HarnessError { + constructor(message: string) { + super(message, 'CODE_RUN_FAILED') + this.name = 'CodeRunFailedError' + } +} + +/** + * Cap for a `tool/code-dispatch` event's `resultSummary`. A log-ergonomics + * constant, not config: the full result already flows to the program; the + * summary exists so log readers see what a sub-call returned at a glance. + */ +const SUMMARY_MAX_CHARS = 200 + +/** Bounded inspect for rendering a program's completion value into the model-facing text. */ +const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const + +/** Join a result's text blocks; a non-text block becomes a placeholder (an MVP limitation, stated in the SDK instructions). */ +function textOf(content: ContentBlock[]): string { + return content + .map((block) => { + switch (block.type) { + case 'text': return block.text + // ContentBlockMap is merge-extensible — future block kinds land here + // deliberately (no assertNever on merge-extensible unions). + default: return `[${block.type} content]` + } + }) + .join('\n') +} + +/** Bound a sub-call's model-facing text for the log event's `resultSummary`. */ +function summarize(text: string): string { + return text.length > SUMMARY_MAX_CHARS ? `${text.slice(0, SUMMARY_MAX_CHARS)}…` : text +} + +/** + * JSON-normalize one binding call's argument: a `JSON.parse(JSON.stringify(…))` + * round-trip, so the value dispatched to the tool and the value logged on the + * `tool/code-dispatch` event are the same JSON value by construction (the + * runtime's structured-clone boundary is wider than JSON; the session log + * accepts only JSON). A value that does not survive (`BigInt`, a circular + * structure, a bare function) rejects that one call with a model-correctable + * error. `undefined` passes through — the tool's own schema validation + * rejects it with its usual "must be an object" feedback. + */ +function jsonNormalizeArgs(value: unknown): unknown { + if (value === undefined) return undefined + let text: string | undefined + try { + text = JSON.stringify(value) + } catch (error: unknown) { + throw new Error(`tool arguments must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`) + } + // JSON.stringify's lib type claims `string`, but a bare function or symbol + // root really yields `undefined` at runtime — the guard is live. + // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition + if (text === undefined) throw new Error('tool arguments must be JSON-serializable (got a value JSON cannot represent)') + return JSON.parse(text) as unknown +} + +/** Render the program's completion value for the model-facing result text (`''` when the program returned nothing). */ +function renderValue(value: unknown): string { + if (value === undefined) return '' + return typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS) +} + +/** The run_code result's `meta` payload (JSON-serializable; `presentResult` narrows it back). */ +interface RunCodeMeta { + logs: CodeRunResult['logs'] + dispatches: number +} + +/** Soft-narrow a result `meta` back to {@link RunCodeMeta} (replay may carry older shapes; presentation must not throw). */ +function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined { + if (typeof meta !== 'object' || meta === null) return undefined + const m = meta as Record + if (!Array.isArray(m.logs) || typeof m.dispatches !== 'number') return undefined + return m as unknown as RunCodeMeta +} + +/** + * Build the `run_code` {@link ToolDefinition}: one required `code` parameter, + * executed through the dispatch bridge described in the module doc. The + * registry registers it under non-native modes. + * @param registry - the owning registry (sub-calls go through its `execute`, + * bindings cover its registered tools). + * @param requireRuntime - resolves `ctx.codeRuntime` or throws the loud + * misconfiguration error (shared with the registry's assembly-time checks). + * @returns the registry-ready definition. + */ +export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => CodeRuntime): ToolDefinition { + return defineTool({ + name: RUN_CODE_NAME, + description: + 'Execute a TypeScript program against the available tools. Write the BODY of an ' + + 'async function (erasable syntax only; top-level `await` and `return` work) and ' + + 'call tools as `await tools.name(args)` per the declarations in the system prompt. ' + + 'Only what you print or return comes back — curate it.', + parameters: { + code: { type: 'string', required: true, description: 'The program: the body of an async TypeScript function.' }, + }, + async execute(args, exec) { + const runtime = requireRuntime() + + // The run-scoped abort: follows the outer signal in, and fires when the + // run settles for ANY reason, so an in-flight sub-dispatch is aborted + // (its executor kills on this signal) instead of orphaned, and + // queued-unstarted dispatches are abandoned. + const runController = new AbortController() + const onOuterAbort = (): void => { runController.abort(exec.signal?.reason) } + if (exec.signal?.aborted) onOuterAbort() + exec.signal?.addEventListener('abort', onOuterAbort, { once: true }) + + let dispatches = 0 + // The per-run serialization queue: every binding call chains onto the + // tail, so even `Promise.all` executes the underlying tool calls one at + // a time in submission order (the tool contract carries no + // concurrency-safety metadata yet). The fold keeps the tail non-rejecting + // so one failed dispatch never poisons the chain. + let queue: Promise = Promise.resolve() + const enqueue = (task: () => Promise): Promise => { + const turn = queue.then(() => { + if (runController.signal.aborted) { + throw new Error(`run_code run is over (${String(runController.signal.reason)}); tool call abandoned`) + } + return task() + }) + queue = turn.then(() => undefined, () => undefined) + return turn + } + + // Read through a call, not a bare property: the abort state genuinely + // changes across awaits, and a direct `.aborted` re-check after one + // would be narrowed away by control flow analysis. + const runOver = (): boolean => runController.signal.aborted + + const binding = (name: string): CodeBindingFunction => async (rawArgs: unknown): Promise => { + if (runOver()) { + throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`) + } + const normalized = jsonNormalizeArgs(rawArgs) + const outcome = await enqueue(async () => { + const n = ++dispatches + const subCallId = CallId(`${String(exec.callId)}:code:${n}`) + const result = await registry.execute({ + callId: subCallId, + name, + arguments: normalized, + ...exec.agent ? { agent: exec.agent } : {}, + signal: runController.signal, + }) + const text = textOf(result.content) + // Sub-call `additionalContext` is deliberately DROPPED here: the + // loop's buffering (append after the step's tool/results) has no + // safe analogue from inside a running run_code — injecting now + // would break tool-call/result adjacency. Deferred until a real + // hook needs it through Code Mode. + exec.agent?.session.append('tool/code-dispatch', { + parentCallId: exec.callId, + subCallId, + name, + arguments: normalized, + isError: result.isError, + resultSummary: summarize(text), + }) + return { text, isError: result.isError } + }) + // A budget expiry or outer cancel that lands while this call was in + // flight already aborted the dispatch; stop the program now rather + // than hand it a result from a run that is over. + if (runOver()) { + throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`) + } + // A failed tool call REJECTS — real code signals failure by throwing, + // so try/catch and Promise.all short-circuiting behave as models + // expect (the error text is the tool's model-facing result text). + if (outcome.isError) throw new Error(outcome.text) + return outcome.text + } + + const functions: Record = {} + for (const schema of registry.schemas()) { + if (schema.name === RUN_CODE_NAME) continue + functions[schema.name] = binding(schema.name) + } + + try { + const result = await runtime.run({ + program: args.code, + bindings: [{ global: 'tools', functions }], + signal: runController.signal, + }) + // Quiescence before returning: fire the run-scoped abort (cancelling + // an in-flight sub-dispatch, abandoning queued ones), then await the + // queue's drain — an aborted sub-call still settles and logs its + // event INSIDE the open turn; nothing can append after we return. + runController.abort('run_code settled') + await queue + + if (result.error) { + const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.map(entry => entry.text).join('\n')}` : '' + throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`) + } + const rendered = renderValue(result.value) + const parts = [result.logs.map(entry => entry.text).join('\n'), rendered].filter(part => part.length > 0) + const meta: RunCodeMeta = { logs: result.logs, dispatches } + return { + content: [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }], + meta, + } + } finally { + exec.signal?.removeEventListener('abort', onOuterAbort) + } + }, + presentCall: args => ({ card: 'generic', title: 'Run code', kind: 'execute', rawInput: args.code }), + presentResult: (_args, result) => { + const meta = asRunCodeMeta(result.meta) + if (!meta) return undefined + const output = meta.logs.map(entry => entry.text).join('\n') + return { + card: 'generic', + title: `Run code (${meta.dispatches} tool call${meta.dispatches === 1 ? '' : 's'})`, + ...output.length > 0 ? { content: [{ type: 'text', text: output }] } : {}, + } + }, + }) +} diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index 39dafd6f1a..e55113316d 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -5,15 +5,26 @@ * `tools/post-execute` (inspect/replace the result, attach context) for * sandbox, permission, and hook plugins to gate or transform a call. * + * The registry also owns HOW its tools are presented to the model — its + * `mode` config: `'native'` (every tool as a wire function definition, + * today's behavior and the default), `'code'` (the wire carries exactly one + * tool, `run_code`, plus a generated TypeScript SDK prompt section), or + * `'both'`. See `code-mode.ts` (the tool + dispatch bridge) and + * `ts-types.ts` (the SDK codegen); design in the Code Mode RFC. + * * @module @deepseek-ai/dsh-tools */ import { Context, Service } from 'cordis' +import z from 'schemastery' import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm' import { HarnessError } from '@deepseek-ai/dsh-llm' import type { Agent, HookContext } from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-system-prompt' +import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime' import type { ToolCallView, ToolResultView } from './presentation.ts' +import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts' +import { renderToolsSdk } from './ts-types.ts' export { defineTool, @@ -38,6 +49,9 @@ export { type StructuredScalar, } from './json-schema.ts' +export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts' +export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts' + // The render-intent vocabulary a tool declares via `presentCall`/`presentResult` // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools` // stays the single public surface for consumers (producers + the ACP bridge). @@ -269,20 +283,100 @@ function errorInfo(error: unknown): ToolErrorInfo | undefined { return error instanceof HarnessError ? { name: error.name, code: error.code } : undefined } +/** How the registry presents its tools to the model (see {@link Config.mode}). */ +export type ToolPresentationMode = 'native' | 'code' | 'both' + +/** Plugin config: how the registered tools are presented to the model. */ +export interface Config { + /** + * The presentation mode. `'native'` (the default) contributes every + * registered tool as a wire function definition — byte-for-byte today's + * behavior. `'code'` contributes exactly ONE wire tool, `run_code`, plus + * the generated `tools:sdk` prompt section declaring every other tool as a + * TypeScript API the program calls. `'both'` contributes every native + * definition AND `run_code` + the SDK section. Non-native modes require a + * loaded `ctx.codeRuntime` whose `language` is `'typescript'` — a missing + * or mismatched runtime rejects every prompt assembly with an actionable + * error (misconfiguration fails loud, before any model request). A + * configured `systemPrompt.toolOrder` naming native tools likewise rejects + * every assembly under `'code'` (those names are no longer contributed) — + * a deployment switching modes updates its order config or drops it. + */ + mode?: ToolPresentationMode +} + /** * Tool registry (`ctx.tools`): tool plugins register definitions; the agent * loop executes calls through the `tools/pre-execute` → dispatch → * `tools/post-execute` pipeline. The registry contributes its schemas into the - * system-prompt assembly. + * system-prompt assembly — WHICH schemas is governed by its `mode` config + * (see {@link Config.mode}); under a non-native mode it also registers the + * `run_code` tool and the `tools:sdk` prompt section itself. */ export class ToolRegistry extends Service { static inject = ['systemPrompt'] - private store = new Map() + static Config: z = z.object({ + mode: z.union(['native', 'code', 'both'] as const).default('native'), + }) - constructor(ctx: Context) { + private store = new Map() + private readonly mode: ToolPresentationMode + + constructor(ctx: Context, config: Config = {}) { super(ctx, 'tools') - ctx.systemPrompt.tools(() => this.schemas()) + // The schema already defaulted an omitted mode; the ?? narrows the + // optional-input type for direct (non-Loader) construction in tests. + this.mode = config.mode ?? 'native' + ctx.systemPrompt.tools(() => this.wireSchemas()) + if (this.mode !== 'native') { + this.register(createRunCodeTool(this, () => this.requireCodeRuntime())) + ctx.systemPrompt.section({ + name: 'tools:sdk', + order: SDK_SECTION_ORDER, + // A lazy thunk over the live store: regenerated at each assembly, in + // lexicographic tool order, so an unchanged tool set renders + // byte-identical text (prefix-cache-friendly) and a mid-session + // registration surfaces exactly like a native-mode tool change. + text: () => { + this.requireCodeRuntime() + return renderToolsSdk(this.schemas().filter(schema => schema.name !== RUN_CODE_NAME)) + }, + }) + } + } + + /** + * The registry's contribution to the wire tool list, per {@link Config.mode}. + * Because `PromptAssembly.tools` is what the loop's request header + * snapshots, the mode's collapse is logged and reconstructable for free. + * Under a non-native mode this is also the loud misconfiguration gate: no + * usable code runtime → every assembly rejects before any model request. + */ + private wireSchemas(): ToolSchema[] { + if (this.mode === 'native') return this.schemas() + this.requireCodeRuntime() + const all = this.schemas() + return this.mode === 'code' ? all.filter(schema => schema.name === RUN_CODE_NAME) : all + } + + /** + * Resolve the code runtime or throw the actionable misconfiguration error. + * Read at use time (assembly / run_code execution), NOT via static + * `inject`: an inject entry would hold `ctx.tools` — and every tool plugin + * behind it — hostage to a code runtime existing even under `mode: + * 'native'` (the loop's optional-backend idiom, same as + * `sessionPersistence`). + */ + private requireCodeRuntime(): CodeRuntime { + const runtime = this.ctx.get('codeRuntime') + if (!runtime) { + throw new Error(`dsh-tools: mode "${this.mode}" requires a code runtime — load a ctx.codeRuntime implementation (e.g. @deepseek-ai/dsh-code-runtime-worker) or set tools mode to "native"`) + } + if (runtime.language !== 'typescript') { + throw new Error(`dsh-tools: mode "${this.mode}" generates a TypeScript SDK, but the loaded code runtime's language is "${runtime.language}"`) + } + return runtime } /** diff --git a/packages/core/tools/src/ts-types.ts b/packages/core/tools/src/ts-types.ts new file mode 100644 index 0000000000..63ebd0f888 --- /dev/null +++ b/packages/core/tools/src/ts-types.ts @@ -0,0 +1,121 @@ +/** + * Code Mode codegen: the pure projection from registered tool schemas to the + * TypeScript SDK text the model programs against (the `tools:sdk` prompt + * section). Sibling of `json-schema.ts` — `schemas()` (native function + * calling) and this module (the generated `declare const tools` surface) are + * two projections of the same store. + * + * TOTAL by design: {@link jsonSchemaToTs} maps the JSON-Schema subset the + * `defineTool` DSL emits and degrades every construct outside it (`$ref`, + * `oneOf`, `integer`, future MCP shapes, …) to `unknown` without ever + * throwing — codegen must never be the thing that fails an assembly. + * Deterministic: a fixed tool set renders byte-identical text (tools in + * lexicographic name order), so the section is prefix-cache-friendly. + * + * @module @deepseek-ai/dsh-tools/src/ts-types + */ + +import type { ToolSchema } from '@deepseek-ai/dsh-llm' + +/** Property names that are valid bare TS identifiers; anything else is quoted. */ +const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/ + +/** Render an object key: bare when it is a valid identifier, quoted otherwise (every name stays reachable, no aliasing). */ +function renderKey(name: string): string { + return IDENTIFIER.test(name) ? name : JSON.stringify(name) +} + +/** One `indent`-deep line prefix (two spaces per level). */ +function pad(indent: number): string { + return ' '.repeat(indent) +} + +/** A one-line JSDoc block for a schema `description`, or no lines when there is none. */ +function docLines(description: unknown, indent: number): string[] { + if (typeof description !== 'string' || description.length === 0) return [] + // Keep the doc a single-line comment per property: descriptions are prose + // (possibly with newlines); collapse whitespace so the rendered SDK stays + // stable and compact. A comment-closer inside the description is escaped so + // it cannot terminate the generated JSDoc early. + const collapsed = description.replace(/\s+/g, ' ').trim() + return [`${pad(indent)}/** ${collapsed.replaceAll('*/', String.raw`*\/`)} */`] +} + +/** + * Map one JSON-Schema node to a TypeScript type literal. Handles exactly the + * subset the `defineTool` DSL emits — `object` (`properties` + `required`), + * `string` (with `enum` → a literal union), `number`, `boolean`, `array` + * (`items`) — and returns `unknown` for anything else, without throwing. + * @param schema - the JSON-Schema node (any shape; hostile inputs degrade). + * @param indent - the indentation level for nested object members. + * @returns the TS type text (multi-line for objects with properties). + */ +export function jsonSchemaToTs(schema: unknown, indent = 0): string { + if (typeof schema !== 'object' || schema === null) return 'unknown' + const node = schema as Record + switch (node.type) { + case 'string': { + if (Array.isArray(node.enum) && node.enum.length > 0 && node.enum.every(value => typeof value === 'string')) { + return node.enum.map(value => JSON.stringify(value)).join(' | ') + } + return 'string' + } + case 'number': return 'number' + case 'boolean': return 'boolean' + case 'array': { + const item = jsonSchemaToTs(node.items, indent) + // Parenthesize a union item type so `('a' | 'b')[]` parses as intended. + return item.includes('|') ? `(${item})[]` : `${item}[]` + } + case 'object': { + const properties = node.properties + if (typeof properties !== 'object' || properties === null) return 'Record' + const entries = Object.entries(properties as Record) + if (entries.length === 0) return 'Record' + const required = new Set(Array.isArray(node.required) ? node.required.filter(name => typeof name === 'string') : []) + const lines: string[] = ['{'] + for (const [name, prop] of entries) { + const description = typeof prop === 'object' && prop !== null ? (prop as Record).description : undefined + lines.push(...docLines(description, indent + 1)) + lines.push(`${pad(indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: ${jsonSchemaToTs(prop, indent + 1)};`) + } + lines.push(`${pad(indent)}}`) + return lines.join('\n') + } + default: return 'unknown' + } +} + +/** The fixed model-facing usage contract rendered above the declarations (see the Code Mode RFC's "What the model sees"). */ +const SDK_INSTRUCTIONS = `## Writing code for run_code + +Pass \`run_code\` the body of an async TypeScript function (erasable syntax only — no \`enum\` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program: + +- Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable. +- A FAILED tool call rejects with an \`Error\` carrying the tool's error text — \`try/catch\` it to handle and continue. +- Calls execute sequentially, even under \`Promise.all\`. +- Emit results with \`return\` and/or \`console.log(...)\`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need. + +The available tools:` + +/** + * Render the full `tools:sdk` prompt section: the fixed usage instructions + * plus one `declare const tools` interface covering every given tool. + * Deterministic — tools are emitted in lexicographic name order, so an + * unchanged tool set produces byte-identical text across assemblies. + * @param schemas - the tool schemas to declare (the caller excludes + * `run_code` itself). + * @returns the complete section text. + */ +export function renderToolsSdk(schemas: ToolSchema[]): string { + const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0) + const members: string[] = [] + for (const schema of sorted) { + members.push(...docLines(schema.description, 1)) + members.push(`${pad(1)}${renderKey(schema.name)}(args: ${jsonSchemaToTs(schema.parameters, 1)}): Promise;`) + } + const declaration = members.length > 0 + ? `declare const tools: {\n${members.join('\n')}\n}` + : 'declare const tools: {}' + return `${SDK_INSTRUCTIONS}\n\n\`\`\`ts\n${declaration}\n\`\`\`` +} diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts new file mode 100644 index 0000000000..32dc161a86 --- /dev/null +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -0,0 +1,523 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime' +import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime' +import ToolRegistry, { CodeRunFailedError, RUN_CODE_NAME, defineTool } from '@deepseek-ai/dsh-tools' +import type { Config, PostToolDecision, ToolExecutionResult } from '@deepseek-ai/dsh-tools' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import type { SessionEventMap } from '@deepseek-ai/dsh-session' + +/** + * Code Mode unit tier (per the RFC's plan): provider contribution per mode, + * misconfiguration rejections, the run_code dispatch bridge (serialization, + * abort, JSON normalization, error mapping, events, quiescence), and HMR + * safety — all against an in-repo fake runtime, exactly the + * interface/implementation/consumer shape the seam promises. + */ + +/** A scriptable in-repo CodeRuntime: each test sets `behavior` to drive the bindings however it needs. */ +class FakeRuntime extends CodeRuntime { + readonly language: string + readonly isolation = 'fake' + behavior: (request: CodeRunRequest) => Promise = () => Promise.resolve({ logs: [] }) + lastRequest?: CodeRunRequest + + constructor(ctx: Context, config: { language?: string } = {}) { + super(ctx) + this.language = config.language ?? 'typescript' + } + + run(request: CodeRunRequest): Promise { + this.lastRequest = request + return this.behavior(request) + } +} + +interface SetupOptions { + mode?: Config['mode'] + runtime?: false | { language?: string } + toolOrder?: string[] +} + +async function setup(options: SetupOptions = {}) { + const ctx = new Context() + await ctx.plugin(SystemPrompt, { ...options.toolOrder ? { toolOrder: options.toolOrder } : {} }) + await ctx.plugin(ToolRegistry, { mode: options.mode ?? 'code' }) + let runtime: FakeRuntime | undefined + if (options.runtime !== false) { + await ctx.plugin(FakeRuntime, options.runtime ?? {}) + runtime = ctx.codeRuntime as FakeRuntime + } + return { ctx, tools: ctx.tools, systemPrompt: ctx.systemPrompt, runtime: runtime! } +} + +/** Register a trivial echo tool; returns the calls it received. */ +function registerEcho(ctx: Context, name = 'echo'): unknown[] { + const calls: unknown[] = [] + ctx.tools.register(defineTool({ + name, + description: `Echo tool ${name}.`, + parameters: { value: { type: 'string', required: true } }, + execute(args) { + calls.push(args) + return Promise.resolve([{ type: 'text' as const, text: `${name}:${args.value}` }]) + }, + })) + return calls +} + +/** A structural fake of the owning agent: captures session appends. */ +function fakeAgent(): { agent: Agent; events: { type: string; data: unknown }[] } { + const events: { type: string; data: unknown }[] = [] + const agent = { + session: { + append: (type: string, data: unknown) => { events.push({ type, data }) }, + }, + } as unknown as Agent + return { agent, events } +} + +/** Dispatch run_code through the registry pipeline, as the loop would. */ +async function runCode(ctx: Context, code: string, extras: { agent?: Agent; signal?: AbortSignal } = {}): Promise { + return ctx.tools.execute({ + callId: CallId('call-1'), + name: RUN_CODE_NAME, + arguments: { code }, + ...extras.agent ? { agent: extras.agent } : {}, + ...extras.signal ? { signal: extras.signal } : {}, + }) +} + +describe('mode-aware wire contribution', () => { + it("mode 'native' contributes every schema, no run_code, no SDK section — and needs no runtime", async () => { + const { ctx, systemPrompt } = await setup({ mode: 'native', runtime: false }) + registerEcho(ctx) + const assembly = await systemPrompt.assemble() + expect(assembly.tools.map(tool => tool.name)).toEqual(['echo']) + expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(false) + }) + + it("mode 'code' contributes exactly [run_code] plus the SDK section declaring the other tools", async () => { + const { ctx, systemPrompt } = await setup({ mode: 'code' }) + registerEcho(ctx) + const assembly = await systemPrompt.assemble() + expect(assembly.tools.map(tool => tool.name)).toEqual([RUN_CODE_NAME]) + const sdk = assembly.sections.find(section => section.name === 'tools:sdk') + expect(sdk?.text).toContain('declare const tools: {') + expect(sdk?.text).toContain('echo(args:') + expect(sdk?.text).not.toContain('run_code(args:') + }) + + it("mode 'both' contributes every native schema plus run_code, and the SDK section", async () => { + const { ctx, systemPrompt } = await setup({ mode: 'both' }) + registerEcho(ctx) + const assembly = await systemPrompt.assemble() + expect(assembly.tools.map(tool => tool.name)).toEqual(['echo', RUN_CODE_NAME]) + expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(true) + }) + + it('renders byte-identical SDK text across consecutive assemblies of an unchanged tool set', async () => { + const { ctx, systemPrompt } = await setup({ mode: 'code' }) + registerEcho(ctx) + const first = await systemPrompt.assemble() + const second = await systemPrompt.assemble() + const text = (assembly: typeof first) => assembly.sections.find(section => section.name === 'tools:sdk')?.text + expect(text(first)).toBe(text(second)) + }) + + it('rejects every assembly when a non-native mode has no code runtime', async () => { + const { systemPrompt } = await setup({ mode: 'code', runtime: false }) + await expect(systemPrompt.assemble()).rejects.toThrow(/requires a code runtime/) + }) + + it("rejects every assembly when the runtime's language is not typescript", async () => { + const { systemPrompt } = await setup({ mode: 'code', runtime: { language: 'python' } }) + await expect(systemPrompt.assemble()).rejects.toThrow(/language is "python"/) + }) + + it("rejects the assembly when toolOrder names a native tool that mode 'code' no longer contributes", async () => { + const { ctx, systemPrompt } = await setup({ mode: 'code', toolOrder: ['echo', ''] }) + registerEcho(ctx) + await expect(systemPrompt.assemble()).rejects.toThrow(/toolOrder lists unregistered tool "echo"/) + }) + + it('removes run_code and the SDK section when the registry fiber disposes (HMR safety)', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt, {}) + await ctx.plugin(FakeRuntime, {}) + const fiber = await ctx.plugin(ToolRegistry, { mode: 'code' }) + expect(ctx.tools.get(RUN_CODE_NAME)).toBeDefined() + await fiber.dispose() + const assembly = await ctx.systemPrompt.assemble() + expect(assembly.tools).toEqual([]) + expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(false) + }) +}) + +describe('the run_code dispatch bridge', () => { + it('bridges tool calls, returns only the curated output, and logs one event per dispatch', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const calls = registerEcho(ctx) + const { agent, events } = fakeAgent() + runtime.behavior = async (request) => { + const tools = request.bindings[0]!.functions + const first = await tools.echo!({ value: 'one' }) + const second = await tools.echo!({ value: 'two' }) + return { logs: [{ source: 'console', level: 'log', text: `saw ${String(first)}` }], value: second } + } + const result = await runCode(ctx, 'const …: string = …', { agent }) + expect(result.isError).toBe(false) + expect(result.content).toEqual([{ type: 'text', text: 'saw echo:one\necho:two' }]) + expect(calls).toEqual([{ value: 'one' }, { value: 'two' }]) + const dispatches = events.filter(event => event.type === 'tool/code-dispatch') + expect(dispatches.map(event => event.data)).toEqual([ + { parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo', arguments: { value: 'one' }, isError: false, resultSummary: 'echo:one' }, + { parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo', arguments: { value: 'two' }, isError: false, resultSummary: 'echo:two' }, + ]) + expect(result.meta).toEqual({ logs: [{ source: 'console', level: 'log', text: 'saw echo:one' }], dispatches: 2 }) + }) + + it('serializes Promise.all dispatches: tool executions never overlap, in submission order', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const intervals: [string, string][] = [] + let active = 0 + ctx.tools.register(defineTool({ + name: 'probe', + description: 'Records execution overlap.', + parameters: { id: { type: 'string', required: true } }, + async execute(args) { + active++ + expect(active, 'probe executions overlapped').toBe(1) + intervals.push(['enter', args.id]) + await new Promise(resolve => setTimeout(resolve, 20)) + intervals.push(['exit', args.id]) + active-- + return [{ type: 'text' as const, text: args.id }] + }, + })) + runtime.behavior = async (request) => { + const tools = request.bindings[0]!.functions + const values = await Promise.all([tools.probe!({ id: 'a' }), tools.probe!({ id: 'b' }), tools.probe!({ id: 'c' })]) + return { logs: [], value: values.join(',') } + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + expect(intervals).toEqual([ + ['enter', 'a'], ['exit', 'a'], + ['enter', 'b'], ['exit', 'b'], + ['enter', 'c'], ['exit', 'c'], + ]) + expect(result.content[0]).toEqual({ type: 'text', text: 'a,b,c' }) + }) + + it('rejects the program-side call when the tool errors, with the tool error text', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + ctx.tools.register(defineTool({ + name: 'fail', + description: 'Always fails.', + parameters: {}, + execute(): Promise { return Promise.reject(new Error('deliberate failure')) }, + })) + runtime.behavior = async (request) => { + try { + await request.bindings[0]!.functions.fail!({}) + return { logs: [], value: 'unreachable' } + } catch (error: unknown) { + return { logs: [], value: `caught: ${error instanceof Error ? error.message : String(error)}` } + } + } + const result = await runCode(ctx, 'program') + expect(result.content[0]).toEqual({ type: 'text', text: 'caught: Error: deliberate failure' }) + }) + + it('a tools/pre-execute deny reaches the program as a binding rejection', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + registerEcho(ctx) + ctx.on('tools/pre-execute', (exec, next) => { + if (exec.name === 'echo') return Promise.resolve({ kind: 'deny' as const, reason: 'not on my watch' }) + return next() + }) + runtime.behavior = async (request) => { + try { + await request.bindings[0]!.functions.echo!({ value: 'x' }) + return { logs: [], value: 'unreachable' } + } catch (error: unknown) { + return { logs: [], value: `denied: ${error instanceof Error ? error.message : String(error)}` } + } + } + const result = await runCode(ctx, 'program') + expect(result.content[0]?.type).toBe('text') + expect((result.content[0] as { text: string }).text).toContain('not on my watch') + }) + + it('rejects a binding argument that does not survive JSON normalization, dispatching nothing', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const calls = registerEcho(ctx) + const { agent, events } = fakeAgent() + runtime.behavior = async (request) => { + try { + await request.bindings[0]!.functions.echo!({ value: 'x', big: 1n }) + return { logs: [], value: 'unreachable' } + } catch (error: unknown) { + return { logs: [], value: error instanceof Error ? error.message : String(error) } + } + } + const result = await runCode(ctx, 'program', { agent }) + expect((result.content[0] as { text: string }).text).toContain('JSON-serializable') + expect(calls).toEqual([]) + expect(events.filter(event => event.type === 'tool/code-dispatch')).toEqual([]) + }) + + it('dispatches the JSON-normalized value: what the tool sees is what the event logs', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const calls = registerEcho(ctx) + const { agent, events } = fakeAgent() + runtime.behavior = async (request) => { + // A Date survives structured clone but is not JSON; the bridge + // normalizes it to its JSON form (an ISO string) BEFORE dispatch. + await request.bindings[0]!.functions.echo!({ value: 'x', when: new Date(0) }).catch(() => undefined) + return { logs: [] } + } + await runCode(ctx, 'program', { agent }) + expect(calls).toEqual([{ value: 'x', when: '1970-01-01T00:00:00.000Z' }]) + const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch'] + expect(dispatch.arguments).toEqual({ value: 'x', when: '1970-01-01T00:00:00.000Z' }) + }) + + it('suppresses sub-call additionalContext (deliberately; pinned)', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + registerEcho(ctx) + ctx.on('tools/post-execute', (exec, _result, next): Promise => { + if (exec.name === 'echo') { + return Promise.resolve({ + kind: 'accept' as const, + additionalContext: { content: [{ type: 'text' as const, text: 'context for the next request' }], source: { kind: 'plugin' as const, plugin: 'test' } }, + }) + } + return next() + }) + runtime.behavior = async (request) => { + await request.bindings[0]!.functions.echo!({ value: 'x' }) + return { logs: [], value: 'done' } + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + // The sub-call's context has no safe outlet mid-run; the parent result + // must not carry it either. + expect(result.additionalContext).toBeUndefined() + }) + + it('converts a failed run into a structured isError result carrying kind, message, and captured logs', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + runtime.behavior = () => Promise.resolve({ + logs: [{ source: 'console', level: 'log', text: 'got this far' }], + error: { kind: 'timeout', message: 'compute budget exhausted (300ms busy)' }, + }) + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(true) + expect(result.error).toEqual({ name: 'CodeRunFailedError', code: 'CODE_RUN_FAILED' }) + const text = (result.content[0] as { text: string }).text + expect(text).toContain('code run failed (timeout)') + expect(text).toContain('compute budget exhausted') + expect(text).toContain('got this far') + }) + + it('CodeRunFailedError is a HarnessError with the CODE_RUN_FAILED code', () => { + const error = new CodeRunFailedError('boom') + expect(error.code).toBe('CODE_RUN_FAILED') + expect(error.name).toBe('CodeRunFailedError') + }) + + it('aborting the outer signal aborts the in-flight sub-dispatch and abandons queued ones', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const seen: string[] = [] + let sawAbort = false + ctx.tools.register(defineTool({ + name: 'slow', + description: 'Slow tool observing its signal.', + parameters: { id: { type: 'string', required: true } }, + async execute(args, exec) { + seen.push(args.id) + await new Promise((resolve) => { + const timer = setTimeout(resolve, 500) + exec.signal?.addEventListener('abort', () => { sawAbort = true; clearTimeout(timer); resolve() }, { once: true }) + }) + return [{ type: 'text' as const, text: args.id }] + }, + })) + const controller = new AbortController() + runtime.behavior = async (request) => { + const tools = request.bindings[0]!.functions + const calls = [tools.slow!({ id: 'first' }).catch(() => 'rejected'), tools.slow!({ id: 'second' }).catch(() => 'rejected')] + setTimeout(() => { controller.abort('user-cancel') }, 50) + await Promise.all(calls) + // A real runtime would be terminated by the abort; the fake honors the + // contract by reporting the abort as the run failure. + return { logs: [], error: { kind: 'abort', message: 'user-cancel' } } + } + const result = await runCode(ctx, 'program', { signal: controller.signal }) + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('code run failed (abort)') + expect(seen).toEqual(['first']) + expect(sawAbort).toBe(true) + }) + + it('runs without an owning agent: dispatches work, event logging is skipped', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const calls = registerEcho(ctx) + runtime.behavior = async (request) => { + await request.bindings[0]!.functions.echo!({ value: 'x' }) + return { logs: [], value: 'ok' } + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + expect(calls).toEqual([{ value: 'x' }]) + }) + + it('executing run_code under a missing runtime is a structured isError, not a crash', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt, {}) + await ctx.plugin(ToolRegistry, { mode: 'code' }) + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('requires a code runtime') + }) + + it('presents the pending call as a generic execute card carrying the program, and the result with the captured output', async () => { + const { ctx } = await setup({ mode: 'code' }) + const tool = ctx.tools.get(RUN_CODE_NAME)! + expect(tool.presentCall?.({ code: 'return 1' })).toEqual({ card: 'generic', title: 'Run code', kind: 'execute', rawInput: 'return 1' }) + const view = tool.presentResult?.({ code: 'return 1' }, { + content: [{ type: 'text', text: 'model-facing' }], + isError: false, + meta: { logs: [{ source: 'console', level: 'log', text: 'printed' }], dispatches: 1 }, + }) + expect(view).toEqual({ card: 'generic', title: 'Run code (1 tool call)', content: [{ type: 'text', text: 'printed' }] }) + // Plural title, and no content when the program printed nothing. + expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [], dispatches: 2 } })) + .toEqual({ card: 'generic', title: 'Run code (2 tool calls)' }) + // Replay with an unrecognizable meta falls back to the generic rendering. + expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { other: true } })).toBeUndefined() + expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false })).toBeUndefined() + }) + + it('renders non-text sub-result blocks as placeholders and truncates long event summaries', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const { agent, events } = fakeAgent() + const long = 'x'.repeat(300) + ctx.tools.register(defineTool({ + name: 'mixed', + description: 'Returns mixed content.', + parameters: {}, + execute() { + return Promise.resolve([ + { type: 'text' as const, text: long }, + { type: 'reasoning' as const, text: 'hidden' }, + ]) + }, + })) + runtime.behavior = async (request) => { + const value = await request.bindings[0]!.functions.mixed!({}) + return { logs: [], value } + } + const result = await runCode(ctx, 'program', { agent }) + expect(result.isError).toBe(false) + expect((result.content[0] as { text: string }).text).toBe(`${long}\n[reasoning content]`) + const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch'] + expect(dispatch.resultSummary.length).toBe(201) + expect(dispatch.resultSummary.endsWith('…')).toBe(true) + }) + + it('rejects undefined, JSON-throwing, and JSON-unrepresentable binding arguments', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + registerEcho(ctx) + runtime.behavior = async (request) => { + const echo = request.bindings[0]!.functions.echo! + const catchMessage = (promise: Promise) => promise.then(() => 'resolved', (error: unknown) => error instanceof Error ? error.message : String(error)) + return { + logs: [], + value: [ + // undefined passes normalization untouched; the tool's own schema + // validation rejects it with its usual feedback. + await catchMessage(echo(undefined)), + // A toJSON that throws a NON-Error propagates out of JSON.stringify. + await catchMessage(echo({ toJSON() { throw 'raw-throw' } })), + // A bare function is a value JSON cannot represent at all. + await catchMessage(echo(() => 1)), + ].join(' | '), + } + } + const result = await runCode(ctx, 'program') + const text = (result.content[0] as { text: string }).text + expect(text).toContain('must be an object') + expect(text).toContain('JSON-serializable: raw-throw') + expect(text).toContain('a value JSON cannot represent') + }) + + it('renders a non-string completion value inspect-style', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + runtime.behavior = () => Promise.resolve({ logs: [], value: { n: 42 } }) + const result = await runCode(ctx, 'program') + expect((result.content[0] as { text: string }).text).toBe('{ n: 42 }') + }) + + it('reports a pre-aborted outer signal as the run failure without dispatching anything', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const calls = registerEcho(ctx) + runtime.behavior = (request) => { + // The fake honors the seam contract for an already-aborted signal. + if (request.signal?.aborted) return Promise.resolve({ logs: [], error: { kind: 'abort' as const, message: String(request.signal.reason) } }) + return Promise.resolve({ logs: [], value: 'unreachable' }) + } + const controller = new AbortController() + controller.abort('too-late') + const result = await runCode(ctx, 'program', { signal: controller.signal }) + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('code run failed (abort)') + expect(calls).toEqual([]) + }) + + it('rejects a binding invoked after the run is over without dispatching it', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const calls = registerEcho(ctx) + const controller = new AbortController() + runtime.behavior = async (request) => { + controller.abort('cancelled-mid-run') + const message = await request.bindings[0]!.functions.echo!({ value: 'x' }) + .then(() => 'resolved', (error: unknown) => error instanceof Error ? error.message : String(error)) + return { logs: [], value: message } + } + const result = await runCode(ctx, 'program', { signal: controller.signal }) + expect(result.isError).toBe(false) + expect((result.content[0] as { text: string }).text).toContain('not dispatched') + expect(calls).toEqual([]) + }) + + it('a tool/code-dispatch event never derives a model message', () => { + const session = new Session(SessionId('code-mode-derive')) + session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) + session.append('tool/code-dispatch', { + parentCallId: CallId('p1'), + subCallId: CallId('p1:code:1'), + name: 'echo', + arguments: { value: 'x' }, + isError: false, + resultSummary: 'echo:x', + }) + const derived = session.deriveMessages() + expect(derived).toHaveLength(1) + expect(derived[0]?.role).toBe('user') + }) + + it('defaults to native mode under direct construction with no config', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt, {}) + const registry = new ToolRegistry(ctx) + expect(registry.get(RUN_CODE_NAME)).toBeUndefined() + const assembly = await ctx.systemPrompt.assemble() + expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(false) + }) +}) diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index cacc2eef66..88cb05cf7c 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { it('boots every shipped tool package and harvests its model-facing schemas', async () => { const catalog = await collectToolCatalog() const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort() - expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) + expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'run_code', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) // Every tool carries a JSON-Schema `parameters` object (what the model sees). for (const entry of catalog) { for (const schema of entry.schemas) { diff --git a/packages/core/tools/tests/ts-types.spec.ts b/packages/core/tools/tests/ts-types.spec.ts new file mode 100644 index 0000000000..df30a58238 --- /dev/null +++ b/packages/core/tools/tests/ts-types.spec.ts @@ -0,0 +1,124 @@ +import { describe, expect, it } from 'vitest' +import { jsonSchemaToTs, renderToolsSdk } from '@deepseek-ai/dsh-tools/src/ts-types.ts' +import { schemaSpecToJsonSchema } from '@deepseek-ai/dsh-tools' +import type { ToolSchema } from '@deepseek-ai/dsh-llm' + +describe('jsonSchemaToTs', () => { + it('maps the defineTool DSL subset', () => { + const cases: [unknown, string][] = [ + [{ type: 'string' }, 'string'], + [{ type: 'number' }, 'number'], + [{ type: 'boolean' }, 'boolean'], + [{ type: 'string', enum: ['a', 'b'] }, '"a" | "b"'], + [{ type: 'array', items: { type: 'number' } }, 'number[]'], + [{ type: 'array', items: { type: 'string', enum: ['x', 'y'] } }, '("x" | "y")[]'], + [{ type: 'array' }, 'unknown[]'], + [{ type: 'object' }, 'Record'], + [{ type: 'object', properties: {} }, 'Record'], + ] + for (const [schema, expected] of cases) { + expect(jsonSchemaToTs(schema), JSON.stringify(schema)).toBe(expected) + } + }) + + it('renders objects with required/optional keys, nested shapes, and per-property docs', () => { + const schema = schemaSpecToJsonSchema({ + path: { type: 'string', required: true, description: 'Absolute file path' }, + limit: { type: 'number' }, + opts: { + type: 'object', + properties: { deep: { type: 'boolean', required: true } }, + }, + }) + expect(jsonSchemaToTs(schema)).toBe([ + '{', + ' /** Absolute file path */', + ' path: string;', + ' limit?: number;', + ' opts?: {', + ' deep: boolean;', + ' };', + '}', + ].join('\n')) + }) + + it('is total: unsupported or hostile constructs degrade to unknown, never throw', () => { + const cases: unknown[] = [ + undefined, + null, + 42, + 'string-schema', + {}, + { type: 'integer' }, + { type: 'null' }, + { oneOf: [{ type: 'string' }] }, + { $ref: '#/defs/x' }, + { type: 'object', properties: 7 }, + { type: 'object', properties: { bad: { $ref: 'x' } } }, + { type: 'string', enum: [1, 2] }, + { type: 'string', enum: [] }, + ] + for (const schema of cases) { + expect(() => jsonSchemaToTs(schema), JSON.stringify(schema)).not.toThrow() + } + expect(jsonSchemaToTs({ type: 'integer' })).toBe('unknown') + expect(jsonSchemaToTs({ oneOf: [] })).toBe('unknown') + expect(jsonSchemaToTs({ type: 'object', properties: 7 })).toBe('Record') + expect(jsonSchemaToTs({ type: 'object', properties: { bad: { $ref: 'x' } }, required: ['bad'] })).toContain('bad: unknown;') + // A non-string-only enum degrades to plain string; an empty one too. + expect(jsonSchemaToTs({ type: 'string', enum: [1, 2] })).toBe('string') + expect(jsonSchemaToTs({ type: 'string', enum: [] })).toBe('string') + // A hostile required list only accepts string members. + expect(jsonSchemaToTs({ type: 'object', properties: { a: { type: 'string' } }, required: [7] })).toContain('a?: string;') + // A property VALUE that is not an object degrades to unknown (and can + // carry no description). + expect(jsonSchemaToTs({ type: 'object', properties: { weird: 42 } })).toContain('weird?: unknown;') + }) + + it('escapes a comment-closer inside a description so the generated JSDoc cannot end early', () => { + const rendered = jsonSchemaToTs({ + type: 'object', + properties: { glob: { type: 'string', description: 'a pattern like packages/*/tool-*/ over here' } }, + }) + expect(rendered).not.toContain('tool-*/ over') + expect(rendered).toContain(String.raw`tool-*\/ over`) + }) +}) + +describe('renderToolsSdk', () => { + const bash: ToolSchema = { + name: 'bash', + description: 'Run a shell command.', + parameters: schemaSpecToJsonSchema({ command: { type: 'string', required: true } }) as unknown as Record, + } + const exotic: ToolSchema = { + name: 'my-mcp.tool', + description: 'Exotic name.', + parameters: schemaSpecToJsonSchema({}) as unknown as Record, + } + + it('declares every tool in lexicographic order with quoted keys for exotic names', () => { + const text = renderToolsSdk([exotic, bash]) + expect(text).toContain('declare const tools: {') + expect(text.indexOf('bash(args:')).toBeGreaterThan(0) + expect(text).toContain('"my-mcp.tool"(args:') + expect(text.indexOf('bash(args:')).toBeLessThan(text.indexOf('"my-mcp.tool"(args:')) + expect(text).toContain('): Promise;') + expect(text).toContain('/** Run a shell command. */') + // The fixed instruction lines the model relies on. + expect(text).toContain('erasable syntax only') + expect(text).toContain('rejects with an `Error`') + expect(text).toContain('sequentially, even under `Promise.all`') + expect(text).toContain('JSON-serializable') + }) + + it('is deterministic: same tool set, byte-identical text regardless of input order', () => { + expect(renderToolsSdk([bash, exotic])).toBe(renderToolsSdk([exotic, bash])) + // Equal names sort stably (the comparator's equal arm). + expect(renderToolsSdk([bash, bash])).toBe(renderToolsSdk([bash, bash])) + }) + + it('renders an empty declaration for an empty tool set', () => { + expect(renderToolsSdk([])).toContain('declare const tools: {}') + }) +}) diff --git a/packages/core/tools/tsconfig.json b/packages/core/tools/tsconfig.json index dedc111d87..68edd3b003 100644 --- a/packages/core/tools/tsconfig.json +++ b/packages/core/tools/tsconfig.json @@ -8,6 +8,12 @@ "src" ], "references": [ + { + "path": "../../core/session" + }, + { + "path": "../../code-runtime/code-runtime" + }, { "path": "../../../vendor/cosmokit" }, diff --git a/packages/hooks/hooks-claude/README.md b/packages/hooks/hooks-claude/README.md index f7afe835d2..306bfdbfeb 100644 --- a/packages/hooks/hooks-claude/README.md +++ b/packages/hooks/hooks-claude/README.md @@ -37,7 +37,7 @@ The hooks **themselves** run in the agent's session workspace: for the agent-sco | `SessionStart` | `agent/session-start` (emit) | additionalContext → `agent.inject()` into the new session (cannot block) | | `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `deny` → `PromptDecision.block`; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a later listener can still block/rewrite) | | `PreToolUse` | `tools/pre-execute` (waterfall) | `deny` → `PreToolDecision.deny`; `ask` → `PreToolDecision.ask` | -| `PostToolUse` | `tools/post-execute` (waterfall) | `deny` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision | +| `PostToolUse` | `tools/post-execute` (waterfall) | `deny` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a Code Mode sub-call’s context is dropped by the run_code bridge — see [the pipeline doc](../../../docs/tool-execution-pipeline.md)) | | `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue`, feeding its reason as next-step steering | | `SubagentStart` | `subagent/start` (emit) | additionalContext → `agent.inject()` into the live child | | `SubagentStop` | `subagent/end` (emit) | observe-only | diff --git a/packages/hooks/hooks-codex/README.md b/packages/hooks/hooks-codex/README.md index 736e8a5100..b3fbc39928 100644 --- a/packages/hooks/hooks-codex/README.md +++ b/packages/hooks/hooks-codex/README.md @@ -43,7 +43,7 @@ The hooks themselves run in the agent's session workspace: for the agent-scoped | `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` | | `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `block` (exit 2) → `PromptDecision.block`; additionalContext-only → delegate via `next()` then fold context onto the downstream decision | | `PreToolUse` | `tools/pre-execute` (waterfall) | `block` → `PreToolDecision.deny` (no `allow`/`ask`) | -| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision | +| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a Code Mode sub-call’s context is dropped by the run_code bridge — see [the pipeline doc](../../../docs/tool-execution-pipeline.md)) | | `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue` with the reason as next-step steering | A tool call's payload carries the real `tool_name` (the same value the matcher tests) and Codex's `tool_input: { command }` shape (the `command` arg when present, else `''`). The matcher subject is the tool name (`PreToolUse`/`PostToolUse`) or the session source (`SessionStart`); `UserPromptSubmit`/`Stop` ignore matchers. diff --git a/packages/ui/acp-agent/package.json b/packages/ui/acp-agent/package.json index e8b4f3723b..940a1cadab 100644 --- a/packages/ui/acp-agent/package.json +++ b/packages/ui/acp-agent/package.json @@ -36,6 +36,7 @@ "@deepseek-ai/dsh-acp": "^0.0.1", "@deepseek-ai/dsh-agent-core": "^0.0.1", "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" }, @@ -45,6 +46,7 @@ "@deepseek-ai/dsh-app-boot": "workspace:^", "@deepseek-ai/dsh-acp": "workspace:^", "@deepseek-ai/dsh-agent-core": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", "cordis": "^4.0.0-rc.6", diff --git a/packages/ui/acp-agent/src/index.ts b/packages/ui/acp-agent/src/index.ts index 898ec9a509..0f5cbc630c 100644 --- a/packages/ui/acp-agent/src/index.ts +++ b/packages/ui/acp-agent/src/index.ts @@ -34,6 +34,7 @@ import type { Context } from 'cordis' import z from 'schemastery' import * as acp from '@deepseek-ai/dsh-acp' import * as agentCore from '@deepseek-ai/dsh-agent-core' +import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' export const name = 'acp-agent' @@ -44,7 +45,8 @@ export const name = 'acp-agent' * pre-created agent — ACP creates agents at `session/new`); `persona` is the * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is * the explicit model-facing tool order (forwarded to the system-prompt plugin); - * `persistenceRoot` is the JSONL backend's directory. + * `tools` is the tool registry's config (its presentation `mode`, forwarded + * through agent-core); `persistenceRoot` is the JSONL backend's directory. */ export interface Config { /** Model name for ACP-created agents (must have a registered adapter). */ @@ -53,6 +55,8 @@ export interface Config { persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ toolOrder?: string[] + /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */ + tools?: ToolsConfig /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string } @@ -64,6 +68,7 @@ export const Config: z = z.object({ // order" (the owning dsh-system-prompt schema does the same), while // schemastery's native [] default would read as an invalid configured list. toolOrder: z.array(z.string()).default(undefined as unknown as string[]), + tools: ToolRegistry.Config, persistenceRoot: z.string().default('./.sessions'), }) @@ -78,6 +83,7 @@ export function apply(ctx: Context, config: Config): void { ctx.plugin(agentCore, { ...config.persona !== undefined ? { persona: config.persona } : {}, ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, + ...config.tools !== undefined ? { tools: config.tools } : {}, }) ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' }) ctx.plugin(acp, { model: config.model }) diff --git a/packages/ui/stdio-agent/package.json b/packages/ui/stdio-agent/package.json index b8cf84cac4..bcac9d8d5d 100644 --- a/packages/ui/stdio-agent/package.json +++ b/packages/ui/stdio-agent/package.json @@ -38,6 +38,7 @@ "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-agent-core": "^0.0.1", "@deepseek-ai/dsh-session": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" @@ -52,6 +53,7 @@ "@deepseek-ai/dsh-agent-core": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" diff --git a/packages/ui/stdio-agent/src/index.ts b/packages/ui/stdio-agent/src/index.ts index 7d36db373e..f0328349aa 100644 --- a/packages/ui/stdio-agent/src/index.ts +++ b/packages/ui/stdio-agent/src/index.ts @@ -43,6 +43,7 @@ import ConsoleExporter from '@cordisjs/plugin-logger-console' import z from 'schemastery' import { AgentId } from '@deepseek-ai/dsh-agent' import { SessionId } from '@deepseek-ai/dsh-session' +import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' import * as agentCore from '@deepseek-ai/dsh-agent-core' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' import * as uiStdio from './stdio-chat.ts' @@ -64,6 +65,8 @@ export interface Config { persona?: string /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */ toolOrder?: string[] + /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */ + tools?: ToolsConfig /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */ persistenceRoot?: string /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */ @@ -83,6 +86,7 @@ export const Config: z = z.object({ // order" (the owning dsh-system-prompt schema does the same), while // schemastery's native [] default would read as an invalid configured list. toolOrder: z.array(z.string()).default(undefined as unknown as string[]), + tools: ToolRegistry.Config, persistenceRoot: z.string().default('./.sessions'), welcome: z.string().default('ready.'), resumeSessionId: z.string(), @@ -100,6 +104,7 @@ export function apply(ctx: Context, config: Config): void { ctx.plugin(agentCore, { ...config.persona !== undefined ? { persona: config.persona } : {}, ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, + ...config.tools !== undefined ? { tools: config.tools } : {}, agents: [{ id: AgentId('main'), model: config.model, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 03a47d6866..88bd9d1147 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -303,13 +303,23 @@ importers: version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) packages/core/tools: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 devDependencies: '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../agent + '@deepseek-ai/dsh-code-runtime': + specifier: workspace:^ + version: link:../../code-runtime/code-runtime '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../session '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../system-prompt @@ -921,6 +931,9 @@ importers: '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) @@ -972,6 +985,9 @@ importers: '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 2848578f49..81829f121a 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -155,8 +155,8 @@ const SERVICE_ROLES: ServiceRole[] = [ title: 'Code-execution seam', mode: 'seam', implementations: ['code-runtime-worker'], - consumers: [], - note: 'Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer).', + consumers: ['tools'], + note: 'Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode).', }, { key: 'fs', @@ -641,7 +641,7 @@ function renderToolPipeline(): string { ' denied["deny or ask
tool body skipped"]', ' toolBody["Registered tool execute() body"]', ` fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}
tool-fs mutations only"]`, - ` owned["Tool-owned session events
${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}"]`, + ` 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"]`, ' context["Buffered additionalContext
context/message after all tool results"]', ` toolResult["Session event: ${mermaidCode('tool/result')}
single model-facing outcome"]`, @@ -661,7 +661,7 @@ function renderToolPipeline(): string { ' toolResult --> presentResult', '```', '', - 'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service.', + 'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service. Code Mode rides the same pipeline twice over: `run_code` is itself a registered tool body, and each tool call its program makes re-enters `ctx.tools.execute()` through BOTH waterfalls — serialized one at a time, logged as a `tool/code-dispatch` session event, with a deny surfacing to the program as a binding rejection (a sub-call\'s `additionalContext` is deliberately dropped — no safe outlet mid-run preserves call/result adjacency).', '', ...maintenanceFooter(maintenance), ].join('\n') diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 24739e1388..67964aae36 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -38,7 +38,7 @@ import { basename, resolve } from 'node:path' import { Context } from 'cordis' import type { ToolSchema } from '@deepseek-ai/dsh-llm' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' -import ToolRegistry from '@deepseek-ai/dsh-tools' +import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools' import LocalBashExecutor from '@deepseek-ai/dsh-bash-local' import LocalFileSystem from '@deepseek-ai/dsh-fs-local' import WebService from '@deepseek-ai/dsh-web' @@ -84,6 +84,13 @@ interface ToolPackage { /** Plug the injected seams + the tool plugin onto a context that already * carries `systemPrompt` + `tools`. */ mount: (ctx: Context) => Promise + /** + * Config for the caller's `ToolRegistry` mount. The registry itself ships a + * model-facing tool (`run_code`, registered under a non-native `mode`), so + * ITS catalog entry boots the registry in the mode that surfaces it; + * every other entry uses the default (native) registry. + */ + toolsConfig?: ToolsConfig /** * A deployment note rendered after the package's tools, for a fact that * booting the package alone cannot show. The registered tool NAME can be a @@ -100,6 +107,20 @@ interface ToolPackage { * guard proves it is exhaustive against the on-disk glob. */ const TOOL_PACKAGES: ToolPackage[] = [ + { + pkg: '@deepseek-ai/dsh-tools', + dir: 'tools', + source: 'packages/core/tools/src/code-mode.ts', + requires: ['ctx.tools', 'ctx.codeRuntime (execution time)', 'ctx.systemPrompt'], + writes: ['tool/call', 'one tool/code-dispatch per bridged sub-call', 'tool/result'], + // The registry's OWN tool: run_code exists only under a non-native mode + // (the registry registers it in its constructor; the code runtime is read + // at assembly/execution time, so the schema harvest needs none mounted). + toolsConfig: { mode: 'code' }, + async mount() {}, + note: + 'Registered by the tool registry itself under `mode: code` / `mode: both` (see the Code Mode RFC). Under `code` it is the ONLY wire tool; the other registered tools are declared to the model as a generated TypeScript SDK prompt section instead, and a program calls them through port-bridged bindings that dispatch through the ordinary tools/pre-execute → tools/post-execute pipeline, one at a time.', + }, { pkg: '@deepseek-ai/dsh-tool-bash', dir: 'tool-bash', @@ -231,7 +252,7 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES // fiber) — the repo's "dispose must reach quiescence" rule. try { await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) + await ctx.plugin(ToolRegistry, entry.toolsConfig ?? {}) await entry.mount(ctx) const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name)) catalog.push({ From 84088300bc437188e8f90f5044ea9907e467afb6 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 13:39:51 +0800 Subject: [PATCH 043/119] fix: pre-dispatch rejection of unloggable args, mutation-proof event copies, proto-safe bindings (Codex round 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three findings from the PR-4 convergence round: (A) A root-undefined binding argument passed normalization untouched, so the sub-call DISPATCHED and only then failed the tool/code-dispatch append (Session.append rejects undefined event data) — a sub-call executed with no log record, violating the nothing-executes-unlogged contract. And the tool received the SAME object later handed to the append, so a tool mutating its args desynced the logged record from what was dispatched (or re-poisoned the append). jsonNormalizeArgs now rejects undefined up front with a model-correctable message and returns TWO independent parses of the canonical JSON text: the tool gets one, the event logs the sibling — identical by construction, mutation-proof. (B) The bridge built its bindings record with plain-object assignment, so a registered tool named __proto__ hit the prototype setter and silently vanished (the runtime host resolves binding names as own properties). The record is now null-prototype with defineProperty, mirroring the worker-side namespace build. (B) The header-pin sanity assertions ran only inside NON-pinning scenarios, so a class consisting solely of its pinning scenario (the two Code Mode classes) would accept a re-recorded pin carrying several headers or a header-delta. A fixtures meta-test now asserts every pinning fixture directly. --- examples/acp-agent/tests/acp.snapshot.ts | 14 +++++ packages/core/tools/src/code-mode.ts | 42 +++++++++------ packages/core/tools/tests/code-mode.spec.ts | 57 ++++++++++++++++++--- 3 files changed, 92 insertions(+), 21 deletions(-) diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index fbc6af65b4..5a22209c16 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -408,6 +408,20 @@ describe('snapshot fixtures', () => { }) }) + it('every pinning fixture carries exactly one request/header and no deltas', async () => { + // The live uniformity guard runs only in NON-pinning scenarios, so a + // class made of just its pinning scenario (the Code Mode classes) would + // otherwise accept a re-recorded pin with several headers or a mid-run + // header-delta — shapes the pin design cannot represent. Assert the + // committed pins directly. + for (const scenario of pinningByClass.values()) { + const fixture = await readFile(join(SNAPSHOTS_DIR, scenario.name, 'session.jsonl'), 'utf8') + const headers = normalizedHeaders(fixture, fixtureContext(fixture)) + expect(headers.length, `${scenario.name}: a pinning fixture must carry exactly one request/header`).toBe(1) + expect(headerDeltaCount(fixture), `${scenario.name}: a pinning fixture must carry no request/header-delta`).toBe(0) + } + }) + it('committed fixtures carry request-header content ONLY in the pinning scenario', async () => { // The whole point of the pin: a system-prompt or tool-schema change must // churn exactly one committed line. A non-pinning fixture that carries the diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index be3b7c91af..904c65ef0e 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -87,17 +87,21 @@ function summarize(text: string): string { } /** - * JSON-normalize one binding call's argument: a `JSON.parse(JSON.stringify(…))` - * round-trip, so the value dispatched to the tool and the value logged on the - * `tool/code-dispatch` event are the same JSON value by construction (the - * runtime's structured-clone boundary is wider than JSON; the session log - * accepts only JSON). A value that does not survive (`BigInt`, a circular - * structure, a bare function) rejects that one call with a model-correctable - * error. `undefined` passes through — the tool's own schema validation - * rejects it with its usual "must be an object" feedback. + * JSON-normalize one binding call's argument into TWO independent parses of + * the same canonical text: `dispatched` goes to the tool, `logged` to the + * `tool/code-dispatch` event — identical by construction (the runtime's + * structured-clone boundary is wider than JSON; the session log accepts only + * JSON), and separate objects, so a tool mutating its args can neither + * desync the log from what was dispatched nor re-poison the append. A value + * that does not survive the round-trip (`undefined` — the log rejects it as + * event data — `BigInt`, a circular structure, a bare function) rejects that + * one call BEFORE dispatch with a model-correctable error: nothing ever + * executes unlogged. */ -function jsonNormalizeArgs(value: unknown): unknown { - if (value === undefined) return undefined +function jsonNormalizeArgs(value: unknown): { dispatched: unknown; logged: unknown } { + if (value === undefined) { + throw new Error('tool arguments must be JSON-serializable (call the tool with an arguments object, e.g. `{}`)') + } let text: string | undefined try { text = JSON.stringify(value) @@ -108,7 +112,7 @@ function jsonNormalizeArgs(value: unknown): unknown { // root really yields `undefined` at runtime — the guard is live. // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition if (text === undefined) throw new Error('tool arguments must be JSON-serializable (got a value JSON cannot represent)') - return JSON.parse(text) as unknown + return { dispatched: JSON.parse(text) as unknown, logged: JSON.parse(text) as unknown } } /** Render the program's completion value for the model-facing result text (`''` when the program returned nothing). */ @@ -198,7 +202,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => const result = await registry.execute({ callId: subCallId, name, - arguments: normalized, + arguments: normalized.dispatched, ...exec.agent ? { agent: exec.agent } : {}, signal: runController.signal, }) @@ -212,7 +216,10 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => parentCallId: exec.callId, subCallId, name, - arguments: normalized, + // The SIBLING parse of the dispatched value: byte-identical JSON, + // but a separate object — a tool mutating its args cannot desync + // this record from what it actually received. + arguments: normalized.logged, isError: result.isError, resultSummary: summarize(text), }) @@ -231,10 +238,15 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => return outcome.text } - const functions: Record = {} + // Null-prototype + defineProperty, mirroring the worker-side namespace + // build: a registered tool named `__proto__` must become an ordinary + // own key (a plain-object assignment would hit the prototype setter, + // silently dropping the binding), and the runtime host resolves + // binding names as own properties only. + const functions: Record = Object.create(null) as Record for (const schema of registry.schemas()) { if (schema.name === RUN_CODE_NAME) continue - functions[schema.name] = binding(schema.name) + Object.defineProperty(functions, schema.name, { enumerable: true, value: binding(schema.name) }) } try { diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index 32dc161a86..7fcd0890e6 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -431,17 +431,18 @@ describe('the run_code dispatch bridge', () => { expect(dispatch.resultSummary.endsWith('…')).toBe(true) }) - it('rejects undefined, JSON-throwing, and JSON-unrepresentable binding arguments', async () => { + it('rejects undefined, JSON-throwing, and JSON-unrepresentable binding arguments BEFORE dispatch', async () => { const { ctx, runtime } = await setup({ mode: 'code' }) - registerEcho(ctx) + const calls = registerEcho(ctx) + const { agent, events } = fakeAgent() runtime.behavior = async (request) => { const echo = request.bindings[0]!.functions.echo! const catchMessage = (promise: Promise) => promise.then(() => 'resolved', (error: unknown) => error instanceof Error ? error.message : String(error)) return { logs: [], value: [ - // undefined passes normalization untouched; the tool's own schema - // validation rejects it with its usual feedback. + // Root undefined must reject up front: the event log rejects it as + // data, and nothing may execute unlogged. await catchMessage(echo(undefined)), // A toJSON that throws a NON-Error propagates out of JSON.stringify. await catchMessage(echo({ toJSON() { throw 'raw-throw' } })), @@ -450,11 +451,55 @@ describe('the run_code dispatch bridge', () => { ].join(' | '), } } - const result = await runCode(ctx, 'program') + const result = await runCode(ctx, 'program', { agent }) const text = (result.content[0] as { text: string }).text - expect(text).toContain('must be an object') + expect(text).toContain('call the tool with an arguments object') expect(text).toContain('JSON-serializable: raw-throw') expect(text).toContain('a value JSON cannot represent') + // None of the three dispatched, none logged. + expect(calls).toEqual([]) + expect(events.filter(event => event.type === 'tool/code-dispatch')).toEqual([]) + }) + + it('logs the value the tool RECEIVED even when the tool mutates its arguments', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const { agent, events } = fakeAgent() + ctx.tools.register(defineTool({ + name: 'mutator', + description: 'Mutates its own args object.', + parameters: { list: { type: 'array', required: true } }, + execute(args) { + args.list.push('injected-by-tool') + return Promise.resolve([{ type: 'text' as const, text: 'mutated' }]) + }, + })) + runtime.behavior = async (request) => { + await request.bindings[0]!.functions.mutator!({ list: ['original'] }) + return { logs: [] } + } + const result = await runCode(ctx, 'program', { agent }) + expect(result.isError).toBe(false) + const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch'] + expect(dispatch.arguments).toEqual({ list: ['original'] }) + }) + + it('exposes a tool named __proto__ as an ordinary own binding', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + ctx.tools.register(defineTool({ + name: '__proto__', + description: 'A prototype-colliding tool name.', + parameters: {}, + execute() { return Promise.resolve([{ type: 'text' as const, text: 'proto-tool-ok' }]) }, + })) + runtime.behavior = async (request) => { + const functions = request.bindings[0]!.functions + expect(Object.getPrototypeOf(functions)).toBeNull() + const value = await functions['__proto__']!({}) + return { logs: [], value } + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + expect(result.content[0]).toEqual({ type: 'text', text: 'proto-tool-ok' }) }) it('renders a non-string completion value inspect-style', async () => { From 5d451bb2a0c2f3c291905f707895b100ed59415c Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 14:06:24 +0800 Subject: [PATCH 044/119] feat(tools): add ToolDefinition.timeoutMs declared+validated via defineTool A tool declares its cooperative timeout budget on its own definition rather than a deployment naming it in a central config map. The field never reaches the model (schemas() whitelists name/description/parameters) and defineTool rejects a non-positive-finite value at authorship. --- packages/core/tools/README.md | 4 ++- packages/core/tools/src/index.ts | 8 +++++ packages/core/tools/src/schema.ts | 11 +++++++ packages/core/tools/tests/tools.spec.ts | 43 +++++++++++++++++++++++++ 4 files changed, 65 insertions(+), 1 deletion(-) diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index d0edd74385..bb1603f68a 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -26,7 +26,7 @@ Tool registry and execution pipeline. Tool plugins register their schemas and ex ### Key types -- `ToolDefinition` — `ToolSchema` + `execute(args, exec): Promise` (the bare array is the model-facing content; the object form additionally attaches an opaque, JSON-serializable `meta` presentation payload persisted on the `tool/result` event and handed back to `presentResult`), plus optional `presentCall(args)` / `presentResult(args, result)` for tool-owned UI presentation (see below). +- `ToolDefinition` — `ToolSchema` + `execute(args, exec): Promise` (the bare array is the model-facing content; the object form additionally attaches an opaque, JSON-serializable `meta` presentation payload persisted on the `tool/result` event and handed back to `presentResult`), plus optional `presentCall(args)` / `presentResult(args, result)` for tool-owned UI presentation (see below). It also carries an optional cooperative timeout budget `timeoutMs?: number` (ms) enforced by `@deepseek-ai/dsh-timeout-policy`, never sent to the model. - `ToolExecution` — one pending tool call: `{ callId, name, arguments, agent?, signal? }`. - `ToolExecutionResult` — outcome: `{ callId, content, isError, error?, additionalContext?, meta? }`. On failure with a `HarnessError`, `error: { name, code }` carries the structured failure class alongside the model-facing text (the loop forwards it onto the `tool/result` session event for retry/sandbox plugins and replay). `additionalContext` (a `HookContext`) ferries any `tools/post-execute` context up to the loop, which buffers it and appends it as a `context/message` after all `tool/result`s in the step. `meta` is the tool's opaque presentation payload from a successful `execute` (the object return form); the loop forwards it onto the `tool/result` session event for result-card rendering. - `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite (changing `arguments`) is deliberately NOT offered (it would desync the pre-execution audit/history/UI from what ran — its own proposed RFC); `ask` degrades to `deny` until the permission system lands. @@ -72,6 +72,8 @@ A `defineTool` tool also **validates the model-generated arguments against its ` See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details. +`defineTool` also validates an optional `timeoutMs` at definition time when present: it must be a positive finite number, or the helper throws — the budget is attached to the produced `ToolDefinition` (for `@deepseek-ai/dsh-timeout-policy`) and never reaches the model. + ### Structured-output schema subset A separate vocabulary for callers that DEMAND a machine-readable value from an agent — the subagent seam's `SubagentStartRequest.outputSchema` (and, by extension, a workflow's `agent({ schema })`). Unlike `SchemaSpec` (the author-facing DSL for tool parameters), a `StructuredOutputSchema` is an object-rooted **raw JSON Schema subset** as data: it travels verbatim to the model as a forced tool's `parameters`, and the produced value is validated against it. diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index 7c6678540c..2b038f1c94 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -138,6 +138,14 @@ export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta /** A registered tool: its schema plus the execution function. */ export interface ToolDefinition extends ToolSchema { execute(args: unknown, exec: ToolExecution): Promise + /** + * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline. + * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it + * is NEVER sent to the model — `schemas()` whitelists only name/description/ + * parameters. Declaring it asserts this tool forwards `exec.signal` to a + * cooperative implementation that can reach quiescence when the signal aborts. + */ + timeoutMs?: number /** * 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 diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts index 16eff5c324..1a428ffd40 100644 --- a/packages/core/tools/src/schema.ts +++ b/packages/core/tools/src/schema.ts @@ -295,6 +295,13 @@ export interface DefineToolOptions { * standard JSON Schema at runtime. */ parameters: S + /** + * Optional cooperative tool-call timeout budget in milliseconds. When given it + * must be a positive finite number; it is attached to the produced + * {@link ToolDefinition} for `@deepseek-ai/dsh-timeout-policy` to enforce and + * is never sent to the model. + */ + timeoutMs?: number /** * Tool execution function. `args` is typed as {@link InferArgs} — zero * casts needed. Returns either a bare {@link ContentBlock}`[]` (model-facing @@ -362,10 +369,14 @@ export function defineTool(options: DefineToolOptions): const userPresentCall = options.presentCall // eslint-disable-next-line @typescript-eslint/unbound-method const userPresentResult = options.presentResult + if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) { + throw new Error(`defineTool(${options.name}): timeoutMs must be a positive finite number`) + } const tool: ToolDefinition = { name: options.name, description: options.description, parameters: schemaSpecToJsonSchema(options.parameters) as unknown as Record, + ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}), async execute(args: unknown, exec: ToolExecution): Promise { // Validate the model-generated args before the typed body runs. On // mismatch we throw ToolArgsError; the registry turns it into an diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts index 5207915df8..98be207159 100644 --- a/packages/core/tools/tests/tools.spec.ts +++ b/packages/core/tools/tests/tools.spec.ts @@ -62,6 +62,17 @@ describe('ToolRegistry', () => { expect(schema.execute).toBeUndefined() }) + it('schemas() excludes timeoutMs — the budget must never reach the model', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ + name: 'budgeted', description: 'has a budget', parameters: {}, timeoutMs: 5_000, + async execute() { return [{ type: 'text' as const, text: 'ok' }] }, + })) + const schema = ctx.tools.schemas().find(s => s.name === 'budgeted') + expect(schema).toBeDefined() + expect('timeoutMs' in (schema as object)).toBe(false) + }) + it('executes a tool and returns its content', async () => { const ctx = await setup() ctx.tools.register(echoTool) @@ -1131,6 +1142,38 @@ describe('defineTool validation (the runtime-validation RFC, part 1)', () => { const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'raw', arguments: {} }) expect(result.isError).toBe(false) }) + + it('attaches a positive-finite timeoutMs to the definition', () => { + const tool = defineTool({ + name: 'x', description: 'd', parameters: {}, timeoutMs: 30_000, + async execute() { return [{ type: 'text' as const, text: 'ok' }] }, + }) + expect(tool.timeoutMs).toBe(30_000) + }) + + it('omits timeoutMs when not declared', () => { + const tool = defineTool({ + name: 'x', description: 'd', parameters: {}, + async execute() { return [{ type: 'text' as const, text: 'ok' }] }, + }) + expect(tool.timeoutMs).toBeUndefined() + }) + + it('throws when timeoutMs is zero or negative', () => { + const make = (ms: number) => defineTool({ + name: 'x', description: 'd', parameters: {}, timeoutMs: ms, + async execute() { return [{ type: 'text' as const, text: 'ok' }] }, + }) + expect(() => make(0)).toThrow('timeoutMs must be a positive finite number') + expect(() => make(-5)).toThrow('positive finite number') + }) + + it('throws when timeoutMs is non-finite', () => { + expect(() => defineTool({ + name: 'x', description: 'd', parameters: {}, timeoutMs: Infinity, + async execute() { return [{ type: 'text' as const, text: 'ok' }] }, + })).toThrow('positive finite number') + }) }) describe('defineTool presentation (presentCall / presentResult)', () => { From d7a27b20df82be857a8c8c86ead561f9d4ac646f Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 14:11:15 +0800 Subject: [PATCH 045/119] test: pin the no-recursive-run_code invariant; document the fold at the drain site (bot review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both bot criticals verified against the code and rejected as exploit paths — pinned instead of patched: The bindings loop already excludes run_code (the skip predates the finding), and the runtime host resolves forged port calls as own properties of the bindings record, so an absent binding is unreachable from a program under any mode. A new both-mode test pins the invariant: the record has no run_code key on any lookup path. The drain await cannot mask a run failure: `queue` is the folded tail (every link swallows its rejection), so `await queue` never rejects and the runtime's own result.error always reaches the CodeRunFailedError conversion — the existing abort test exercises exactly the queued-abandonment-plus-run-failure scenario. Stated at the drain site so the fold's purpose is explicit. --- packages/core/tools/src/code-mode.ts | 4 ++++ packages/core/tools/tests/code-mode.spec.ts | 20 ++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index 904c65ef0e..970bb6e208 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -259,6 +259,10 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => // an in-flight sub-dispatch, abandoning queued ones), then await the // queue's drain — an aborted sub-call still settles and logs its // event INSIDE the open turn; nothing can append after we return. + // `queue` is the FOLDED tail (every link swallows its rejection into + // undefined), so this await cannot itself reject — an abandoned + // queued call can never mask the runtime's own `result.error` below; + // rejections surface only on the per-call promises the program holds. runController.abort('run_code settled') await queue diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index 7fcd0890e6..7cbceb5361 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -119,6 +119,26 @@ describe('mode-aware wire contribution', () => { expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(true) }) + it("never exposes run_code to programs, even under mode 'both' (no recursive dispatch path)", async () => { + const { ctx, runtime } = await setup({ mode: 'both' }) + registerEcho(ctx) + runtime.behavior = (request) => { + const functions = request.bindings[0]!.functions + return Promise.resolve({ + logs: [], + value: JSON.stringify({ + names: Object.keys(functions).sort(), + // Own-property AND prototype-chain reads both come back empty — + // there is no handle a program could re-enter run_code through. + runCode: String(functions[RUN_CODE_NAME]), + }), + }) + } + const result = await runCode(ctx, 'program') + expect(result.isError).toBe(false) + expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ names: ['echo'], runCode: 'undefined' }) + }) + it('renders byte-identical SDK text across consecutive assemblies of an unchanged tool set', async () => { const { ctx, systemPrompt } = await setup({ mode: 'code' }) registerEcho(ctx) From db26ef479dfa91dc73d8254c860f57c4265cedfa Mon Sep 17 00:00:00 2001 From: kingwl Date: Wed, 8 Jul 2026 14:24:20 +0800 Subject: [PATCH 046/119] feat(guard): add the repeat-tool-guard plugin --- AGENTS.md | 5 +- docs/config-catalog.md | 24 ++ docs/event-producer-consumer.md | 6 +- docs/module-graph.md | 6 + packages/README.md | 1 + packages/guard/README.md | 9 + packages/guard/repeat-tool-guard/README.md | 36 ++ packages/guard/repeat-tool-guard/package.json | 41 ++ packages/guard/repeat-tool-guard/src/index.ts | 243 ++++++++++++ .../tests/repeat-tool-guard.spec.ts | 372 ++++++++++++++++++ .../guard/repeat-tool-guard/tsconfig.json | 30 ++ pnpm-lock.yaml | 28 ++ tsconfig.base.json | 1 + tsconfig.build.json | 1 + tsconfig.json | 1 + 15 files changed, 799 insertions(+), 5 deletions(-) create mode 100644 packages/guard/README.md create mode 100644 packages/guard/repeat-tool-guard/README.md create mode 100644 packages/guard/repeat-tool-guard/package.json create mode 100644 packages/guard/repeat-tool-guard/src/index.ts create mode 100644 packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts create mode 100644 packages/guard/repeat-tool-guard/tsconfig.json diff --git a/AGENTS.md b/AGENTS.md index 2cd72aff60..911b368a62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,11 +19,12 @@ packages/ Harness packages at packages///, all named @deepseek-ai compact/ compaction seam + basic backend subagent/ subagent seam + spawn/fork/ACP backends + delegation tool todo/ the todo_write tool + guard/ loop-hygiene plugins hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends ui/ ACP bridge + app-boot glue + the stdio/ACP app bins - support/ dev/test infrastructure: invariants, llm-replay, subagent-mock - util/ zero-dependency utilities (Branded) + support/ dev/test infrastructure packages + util/ zero-dependency utilities examples/ Runnable demos: thin cordis.yml leaves over the app packages (see examples/AGENTS.md) docs/ architecture, generated catalogs, RFCs, postmortems, cookbook (see docs/AGENTS.md) scripts/ repo gates and generators diff --git a/docs/config-catalog.md b/docs/config-catalog.md index e268f63da6..18a1387baa 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -353,6 +353,30 @@ export interface Config { Source: [`packages/support/llm-replay/src/index.ts:429`](../packages/support/llm-replay/src/index.ts) +## `@deepseek-ai/dsh-repeat-tool-guard` + +```ts config-catalog +/** + * Plugin config, validated by the same-named schemastery schema plus the + * load-time checks in `apply` (misconfiguration fails loud: an empty + * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at + * plugin load, never a silent fall-back). `include`/`exclude` entries are + * `*`-wildcard predicates over tool names at call time, not references to + * registry entries — a pattern matching no currently registered tool is valid + * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools). + */ +export interface Config { + /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */ + thresholds?: number[] + /** Tool-name patterns to track; empty means every tool is tracked. */ + include?: string[] + /** Tool-name patterns transparent to the chain (neither count nor reset). */ + exclude?: string[] +} +``` + +Source: [`packages/guard/repeat-tool-guard/src/index.ts:55`](../packages/guard/repeat-tool-guard/src/index.ts) + ## `@deepseek-ai/dsh-session-persistence-jsonl` Requires: `sessions` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index c10d7caa52..1736981563 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -11,11 +11,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:271`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/error` | `emit` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:349`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:362`](../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/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:362`](../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), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | | `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:385`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:304`](../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:280`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:280`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:395`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:408`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | @@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | -| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:76`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`. diff --git a/docs/module-graph.md b/docs/module-graph.md index c08b1fd171..b91d12234b 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -79,6 +79,9 @@ flowchart TD pkg_app_boot["app-boot"] pkg_stdio_agent["stdio-agent"] end + subgraph group_guard["packages/guard"] + pkg_repeat_tool_guard["repeat-tool-guard"] + end pkg_llm --> pkg_brand pkg_bash --> pkg_brand pkg_llm_deepseek --> pkg_llm @@ -157,6 +160,8 @@ flowchart TD pkg_acp --> pkg_session pkg_acp --> pkg_session_persistence pkg_acp --> pkg_tools + pkg_repeat_tool_guard --> pkg_agent + pkg_repeat_tool_guard --> pkg_tools pkg_agent_core --> pkg_agent pkg_agent_core --> pkg_agent_loop pkg_agent_core --> pkg_invariants @@ -243,6 +248,7 @@ flowchart TD | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | +| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | diff --git a/packages/README.md b/packages/README.md index f07e0d5a36..5a291a6012 100644 --- a/packages/README.md +++ b/packages/README.md @@ -16,6 +16,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface | +| [`guard/`](guard/README.md) | Loop-hygiene guard family: advisory plugins that nudge the model out of unproductive patterns (repeat-tool-guard) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | | [`ui/`](ui/README.md) | Editor/client integration surfaces (the ACP bridge) + the app packages | Product — stable surface | diff --git a/packages/guard/README.md b/packages/guard/README.md new file mode 100644 index 0000000000..9198698b20 --- /dev/null +++ b/packages/guard/README.md @@ -0,0 +1,9 @@ +# guard/ — loop-hygiene guard family + +Behavioral guard plugins that watch the agent loop for unproductive patterns and nudge the model back on course. A single **product** package — there is no interface/implementation seam here, because a guard is a self-contained consumer of existing core seams (`tools/post-execute`, `agent/prompt-submit`, `agent/status`), not a swappable capability. + +| Package | Role | ctx key | +|---|---|---| +| `repeat-tool-guard/` | Advisory reminders when an agent loops on identical tool calls | (listens on `ctx.tools`' waterfalls) | + +Reminders travel as `additionalContext` on the `tools/post-execute` decision; the agent loop appends them as logged `context/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log. diff --git a/packages/guard/repeat-tool-guard/README.md b/packages/guard/repeat-tool-guard/README.md new file mode 100644 index 0000000000..647426e382 --- /dev/null +++ b/packages/guard/repeat-tool-guard/README.md @@ -0,0 +1,36 @@ +# @deepseek-ai/dsh-repeat-tool-guard + +An advisory loop-breaker, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The decision (retry differently, gather more evidence, or finish) stays entirely with the model: a legitimately repeated call is delayed by nothing and blocked by nothing. Decision record: [the repeat-tool-guard RFC](../../../docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md). + +## Config + +```yaml +- id: repeat-tool-guard + name: '@deepseek-ai/dsh-repeat-tool-guard' + config: + thresholds: [3, 5, 8] # default; consecutive counts that trigger a reminder + include: [] # tool-name patterns to track; empty ⇒ all tools + exclude: [todo_write] # tool-name patterns transparent to the chain +``` + +`thresholds` fails loud at plugin load: an empty list, a non-integer, a value below 2, or a duplicate throws, never a silent fall-back to defaults. The list is normalized to ascending order; the FIRST threshold delivers a short generic nudge, every later threshold delivers the detailed form naming the tool, the run length, and the canonical arguments. + +`include`/`exclude` entries support `*` wildcards and are predicates over whatever tools exist at call time, not references to registry entries — a pattern matching no currently registered tool is NOT an error (`exclude: [mcp_*]` stays valid in a deployment that loads no MCP tools), unlike `toolOrder`'s referent check. + +## Chain semantics + +The chain key is `(tool name, canonical arguments)` — canonicalization is a deep key-sort plus `JSON.stringify`, so argument objects differing only in property order count as identical. A call identical to the previous tracked call increments the agent's consecutive counter; a different tracked call resets it to 1. + +- **Untracked calls are transparent to the chain.** A call excluded by `include`/`exclude` neither increments nor resets the counter, so `grep X → todo_write → grep X` still counts as two consecutive `grep X` when `todo_write` is excluded. This is what makes exclusion useful: bookkeeping tools interleaved into a loop must not launder it. +- **Denied calls count.** Detection sits on `tools/post-execute`, which also runs for calls a `tools/pre-execute` listener denied — a model hammering a denied call is exactly the loop worth breaking. +- **Calls without an agent are ignored.** A direct `ctx.tools.execute()` caller has no model to remind and no `AgentId` to key on. +- **Per-agent keying.** The tool registry is context-level and subagents interleave through the same waterfall, so chains are keyed by `AgentId`; one agent's repetition never trips another's reminder. A user prompt (`agent/prompt-submit`) resets the submitting agent's chain; agent disposal drops its state. +- **In-memory only.** A session resumed from persistence starts with a fresh chain — the guard is a heuristic nudge, not a logged invariant, later reminders are the accepted cost. + +## Reminder delivery + +Reminders ride the post-execute decision's `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as a `context/message` after the step's tool results, which the session renders as the tagged synthetic-user envelope — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and folds its reminder onto the downstream decision (both variants — a blocked call still gets the nudge); when a downstream listener attached its own `additionalContext`, the fold concatenates content and carries the guard's `source` (a `HookContext` holds one `MessageSource`; `source.kind` is what framing depends on). + +## Testing + +Unit suites drive a real agent loop against a mock adapter (no network) and cover the chain semantics above to per-file 100%. The snapshot tier owns the transcript surface: a scripted-replay scenario repeats a call five times and pins both reminder tiers (gentle at 3, detailed at 5) as `context/message`s in the ACP transcript. diff --git a/packages/guard/repeat-tool-guard/package.json b/packages/guard/repeat-tool-guard/package.json new file mode 100644 index 0000000000..9b085bb015 --- /dev/null +++ b/packages/guard/repeat-tool-guard/package.json @@ -0,0 +1,41 @@ +{ + "name": "@deepseek-ai/dsh-repeat-tool-guard", + "description": "Repeat-tool-call guard plugin: advisory reminders when an agent loops on identical tool calls", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "dependencies": { + "schemastery": "^3.18.0" + }, + "peerDependencies": { + "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/guard/repeat-tool-guard/src/index.ts b/packages/guard/repeat-tool-guard/src/index.ts new file mode 100644 index 0000000000..e32d9efd67 --- /dev/null +++ b/packages/guard/repeat-tool-guard/src/index.ts @@ -0,0 +1,243 @@ +/** + * Repeat-tool-call guard: advisory loop-breaker for agents stuck re-issuing + * the same tool call with identical arguments. + * + * Not a model-facing tool — it registers no tool, never vetoes or rewrites a + * call, and adds exactly one behavior: watch each agent's stream of tool calls + * through the `tools/post-execute` waterfall, count runs of consecutive calls + * to the same tool with identical canonicalized arguments, and at configured + * run lengths fold an escalating advisory reminder onto the decision's + * `additionalContext`. The loop appends that context as a logged + * `context/message` after the step's tool results, so the reminder is + * model-visible, source-attributed, and reconstructable from the session log + * with no new session event. Decision record: + * docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md. + * + * ```yaml + * - id: repeat-tool-guard + * name: '@deepseek-ai/dsh-repeat-tool-guard' + * config: + * thresholds: [3, 5, 8] # consecutive counts that trigger a reminder + * include: [] # tool-name patterns to track; empty = all tools + * exclude: [todo_write] # tool-name patterns transparent to the chain + * ``` + * + * Chain state is keyed per {@link AgentId} — the tool registry is a + * context-level singleton whose waterfalls interleave every agent's calls, so + * a shared counter would let one agent's repetition trip another's reminder. + * State is in-memory only: a session resumed from persistence starts with a + * fresh chain (the guard is a heuristic nudge, not a logged invariant). + * + * Plugin export shape: named exports, NO default. The cordis Loader's + * `unwrapExports` does `exports.default ?? exports`, so a stray default would + * collapse the module to the bare `apply` (see docs/postmortem/0001). + * + * @module @deepseek-ai/dsh-repeat-tool-guard + */ + +import type { Context } from 'cordis' +import z from 'schemastery' +import type { AgentId, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent' +import type { MessageSource } from '@deepseek-ai/dsh-llm' +import type { PostToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools' + +export const name = 'repeat-tool-guard' + +/** + * Plugin config, validated by the same-named schemastery schema plus the + * load-time checks in `apply` (misconfiguration fails loud: an empty + * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at + * plugin load, never a silent fall-back). `include`/`exclude` entries are + * `*`-wildcard predicates over tool names at call time, not references to + * registry entries — a pattern matching no currently registered tool is valid + * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools). + */ +export interface Config { + /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */ + thresholds?: number[] + /** Tool-name patterns to track; empty means every tool is tracked. */ + include?: string[] + /** Tool-name patterns transparent to the chain (neither count nor reset). */ + exclude?: string[] +} + +export const Config: z = z.object({ + thresholds: z.array(z.number()).default([3, 5, 8]), + include: z.array(z.string()).default([]), + exclude: z.array(z.string()).default([]), +}) + +/** + * The `{kind:'plugin'}` source stamped on every reminder this guard injects — + * the label is load-bearing (an unlabeled context would render as a user + * prompt in derived history). + */ +const PLUGIN_SOURCE: MessageSource = { kind: 'plugin', plugin: 'repeat-tool-guard' } + +/** + * The gentle first-threshold reminder. Keyed to `thresholds[0]`, not a literal + * count, so a custom first threshold keeps the gentle-then-detailed escalation. + */ +const GENTLE_REMINDER = + 'You are repeating the exact same tool call with identical arguments. ' + + 'Carefully analyze the previous result before calling again: if the task is ' + + 'not complete, try a different approach or different arguments instead of ' + + 'repeating the call.' + +/** The detailed later-threshold reminder naming the tool, the run length, and the canonical arguments. */ +function detailedReminder(toolName: string, count: number, canonicalArguments: string): string { + return 'Repeated tool call detected:\n' + + `- tool: ${toolName}\n` + + `- consecutive_calls: ${count}\n` + + `- arguments: ${canonicalArguments}\n` + + 'The repeated calls are not making progress. Do not call this tool with ' + + 'these exact arguments again. Inspect the latest result and choose a ' + + 'different action, different arguments, or finish the task if enough ' + + 'evidence has been gathered.' +} + +/** + * Deep key-sort of a parsed-JSON value so two argument objects that differ + * only in property order canonicalize identically. Arguments reach the guard + * as the loop's `JSON.parse` output (or its raw-string fallback for malformed + * argument JSON), so JSON's value domain is the whole input domain — no + * bigint, cycle, or `undefined` handling exists because no input path can + * produce them. + */ +function sortJsonValue(value: unknown): unknown { + if (Array.isArray(value)) return value.map(sortJsonValue) + if (value !== null && typeof value === 'object') { + const record = value as Record + const sorted: Record = {} + for (const key of Object.keys(record).sort()) { + sorted[key] = sortJsonValue(record[key]) + } + return sorted + } + return value +} + +/** Canonical string form of a call's arguments: deep key-sort, then stringify. */ +function canonicalize(argumentsValue: unknown): string { + return JSON.stringify(sortJsonValue(argumentsValue)) +} + +/** Compile one `*`-wildcard pattern to an anchored RegExp (every other regex metacharacter is matched literally). */ +function wildcardToRegExp(pattern: string): RegExp { + const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, String.raw`\$&`) + return new RegExp(`^${escaped.replaceAll('*', '.*')}$`) +} + +/** + * Validate `thresholds` per the fail-loud contract and return them sorted + * ascending (the escalation rule reads `thresholds[0]` as the gentle tier, so + * order is normalized here, once). + */ +function validateThresholds(values: number[]): number[] { + if (values.length === 0) { + throw new Error('repeat-tool-guard: `thresholds` must not be empty') + } + for (const value of values) { + if (!Number.isInteger(value) || value < 2) { + throw new Error(`repeat-tool-guard: invalid threshold ${value} — every threshold must be an integer >= 2`) + } + } + if (new Set(values).size !== values.length) { + throw new Error('repeat-tool-guard: `thresholds` must not contain duplicates') + } + return [...values].sort((a, b) => a - b) +} + +/** + * Concatenate the guard's reminder context with a downstream listener's + * optional one so folding drops neither. The merged block carries the guard's + * `source` — a `HookContext` holds one `MessageSource` and the seam cannot + * represent mixed provenance; the rendered `context/message` only + * distinguishes by `source.kind`, so a downstream plugin's text is still + * correctly framed as plugin context. + */ +function concatContext(ours: HookContext, theirs: HookContext | undefined): HookContext { + if (!theirs) return ours + return { content: [...ours.content, ...theirs.content], source: ours.source } +} + +/** One agent's consecutive-repeat chain: the last tracked call's identity key and its run length. */ +interface Chain { + key: string + count: number +} + +/** + * Install the guard's listeners. + * @param ctx - plugin context; listeners are scoped to it and disposed with it. + * @param config - validated {@link Config}; `thresholds` is re-checked fail-loud here. + */ +export function apply(ctx: Context, config: Config): void { + // schemastery's .default() guarantees the arrays are set after validation. + const thresholds = validateThresholds(config.thresholds as number[]) + const thresholdSet = new Set(thresholds) + const includePatterns = (config.include as string[]).map(wildcardToRegExp) + const excludePatterns = (config.exclude as string[]).map(wildcardToRegExp) + + const chains = new Map() + + /** Whether a tool participates in the chain (untracked calls are transparent: they neither count nor reset). */ + function tracked(toolName: string): boolean { + if (includePatterns.length > 0 && !includePatterns.some(pattern => pattern.test(toolName))) return false + return !excludePatterns.some(pattern => pattern.test(toolName)) + } + + /** + * Advance the calling agent's chain for one attempt and return the reminder + * to deliver, if this attempt's run length hits a configured threshold. + * Counting happens here — in post-execute — because denied calls also flow + * through this waterfall (`ToolRegistry.execute` routes a deny through the + * same pipeline), and a model hammering a denied call is exactly the loop + * worth breaking. + */ + function observe(exec: ToolExecution): HookContext | undefined { + // A direct `ctx.tools.execute()` caller has no model to remind and no id + // to key on; only agent-loop calls participate. + if (!exec.agent) return undefined + if (!tracked(exec.name)) return undefined + const canonical = canonicalize(exec.arguments) + const key = JSON.stringify([exec.name, canonical]) + const chain = chains.get(exec.agent.id) + const count = chain !== undefined && chain.key === key ? chain.count + 1 : 1 + chains.set(exec.agent.id, { key, count }) + if (!thresholdSet.has(count)) return undefined + const text = count === thresholds[0] ? GENTLE_REMINDER : detailedReminder(exec.name, count, canonical) + return { content: [{ type: 'text', text }], source: PLUGIN_SOURCE } + } + + // Observe-and-enrich, never veto: count first (state advances regardless of + // the downstream outcome), DELEGATE so a later listener can still block or + // replace, then fold the reminder onto whatever came back — additionalContext + // rides both decision variants, so a blocked call still gets the nudge. + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { + const reminder = observe(exec) + const downstream = await next() + if (!reminder) return downstream + if (downstream.kind === 'block') { + return { kind: 'block', feedback: downstream.feedback, additionalContext: concatContext(reminder, downstream.additionalContext) } + } + return { + kind: 'accept', + ...downstream.content !== undefined ? { content: downstream.content } : {}, + additionalContext: concatContext(reminder, downstream.additionalContext), + } + }) + + // A user interjection changes the context; repetition across it is not a + // loop. Pure reset hook: always delegates (attaching nothing, vetoing + // nothing). + ctx.on('agent/prompt-submit', (agent, _content, _source, next): Promise => { + chains.delete(agent.id) + return next() + }) + + // Drop state when an agent goes away, bounding the map over harness lifetime. + ctx.on('agent/status', (agent, status) => { + if (status === 'disposed') chains.delete(agent.id) + }) +} diff --git a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts new file mode 100644 index 0000000000..df59eb1019 --- /dev/null +++ b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts @@ -0,0 +1,372 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService, { CallId } from '@deepseek-ai/dsh-llm' +import SessionStore, { type SessionEvent } from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import * as RepeatToolGuard from '@deepseek-ai/dsh-repeat-tool-guard' +import type { Config } from '@deepseek-ai/dsh-repeat-tool-guard' +import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' + +/** + * Behavior suite for the repeat-tool-call guard: chain semantics (identical / + * different-tracked / untracked-transparent / per-agent / resets), threshold + * escalation incl. the `thresholds[0]` gentle-text rule, canonicalization, + * fold-onto-downstream-decision, and fail-loud config validation — all driven + * through a real agent loop against a scripted mock adapter (no network). + */ + +/** Boot the core spine + the guard; the caller registers adapters and extra listeners. */ +async function harness(config: Config = {}): Promise { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(RepeatToolGuard, config) + ctx.tools.register(defineTool({ name: 'probe', description: 'p', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } })) + ctx.tools.register(defineTool({ name: 'other', description: 'o', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } })) + return ctx +} + +function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise { + return new Promise((resolve) => { const d = ctx.on('agent/status', (s, st) => { if (s === agent && st === 'idle') { d(); resolve() } }) }) +} + +/** Every `context/message` in the agent's log, flattened to joined text + source for terse assertions. */ +function reminders(agent: ReactLoopAgent): { text: string; source: unknown }[] { + return [...agent.session.events] + .filter((e): e is SessionEvent<'context/message'> => e.type === 'context/message') + .map(e => ({ + text: e.data.content.map(block => block.type === 'text' ? block.text : '').join('|'), + source: e.data.source, + })) +} + +const GUARD_SOURCE = { kind: 'plugin', plugin: 'repeat-tool-guard' } + +describe('threshold escalation', () => { + it('reminds gently at the first default threshold (3) and in detail at the second (5)', async () => { + const ctx = await harness() + const adapter = new MockAdapter([ + ...Array.from({ length: 5 }, (_, i) => toolCallResponse(`c${i}`, 'probe', { q: 'same' })), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(2) + expect(found[0]!.text).toContain('repeating the exact same tool call') + expect(found[0]!.source).toEqual(GUARD_SOURCE) + expect(found[1]!.text).toContain('consecutive_calls: 5') + expect(found[1]!.text).toContain('- tool: probe') + expect(found[1]!.text).toContain('{"q":"same"}') + expect(found[1]!.source).toEqual(GUARD_SOURCE) + }) + + it('keys the gentle text to thresholds[0], not the literal 3', async () => { + const ctx = await harness({ thresholds: [4, 2] }) // unsorted on purpose: normalized ascending + const adapter = new MockAdapter([ + ...Array.from({ length: 4 }, (_, i) => toolCallResponse(`c${i}`, 'probe', {})), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(2) + expect(found[0]!.text).toContain('repeating the exact same tool call') // gentle at 2 + expect(found[1]!.text).toContain('consecutive_calls: 4') // detailed at 4 + }) +}) + +describe('chain semantics', () => { + it('a different tracked call resets the chain', async () => { + const ctx = await harness() + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + toolCallResponse('c2', 'probe', { q: 1 }), + toolCallResponse('c3', 'other', {}), // tracked, different → reset + toolCallResponse('c4', 'probe', { q: 1 }), + toolCallResponse('c5', 'probe', { q: 1 }), + toolCallResponse('c6', 'probe', { q: 1 }), // 3rd consecutive AFTER the reset + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(reminders(agent)).toHaveLength(1) + }) + + it('excluded calls are transparent: they neither count nor reset', async () => { + const ctx = await harness({ exclude: ['other'] }) + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + toolCallResponse('c2', 'other', {}), // excluded → invisible to the chain + toolCallResponse('c3', 'probe', { q: 1 }), + toolCallResponse('c4', 'other', {}), + toolCallResponse('c5', 'probe', { q: 1 }), // 3rd consecutive probe + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(1) + expect(found[0]!.text).toContain('repeating the exact same tool call') + }) + + it('include patterns track only matching tools (wildcard star)', async () => { + const ctx = await harness({ include: ['pro*'] }) + const adapter = new MockAdapter([ + toolCallResponse('c1', 'other', {}), + toolCallResponse('c2', 'other', {}), + toolCallResponse('c3', 'other', {}), // 3 identical, but untracked + toolCallResponse('c4', 'probe', {}), + toolCallResponse('c5', 'probe', {}), + toolCallResponse('c6', 'probe', {}), // 3 identical, tracked + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(1) + expect(found[0]!.text).toContain('repeating the exact same tool call') + }) + + it('escapes regex metacharacters in patterns (a dot matches only a literal dot)', async () => { + const ctx = await harness({ exclude: ['pr.be'] }) // would match 'probe' as a regex; must not as a wildcard + const adapter = new MockAdapter([ + ...Array.from({ length: 3 }, (_, i) => toolCallResponse(`c${i}`, 'probe', {})), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(reminders(agent)).toHaveLength(1) // probe was NOT excluded + }) + + it('canonicalization ignores property order, deeply', async () => { + const ctx = await harness() + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { a: 1, nested: { x: [1, 2], y: null } }), + toolCallResponse('c2', 'probe', { nested: { y: null, x: [1, 2] }, a: 1 }), + toolCallResponse('c3', 'probe', { a: 1, nested: { x: [1, 2], y: null } }), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(reminders(agent)).toHaveLength(1) // all three canonicalize identically + }) + + it('keys chains per agent: one agent repeating never trips another', async () => { + const ctx = await harness() + ctx.llm.registerAdapter(['mock-a'], new MockAdapter([ + toolCallResponse('a1', 'probe', { q: 1 }), + toolCallResponse('a2', 'probe', { q: 1 }), + textResponse('done'), + ])) + ctx.llm.registerAdapter(['mock-b'], new MockAdapter([ + toolCallResponse('b1', 'probe', { q: 1 }), + toolCallResponse('b2', 'probe', { q: 1 }), + toolCallResponse('b3', 'probe', { q: 1 }), + textResponse('done'), + ])) + const agentA = ctx.agentLoop.create(AgentId('a'), { model: 'mock-a' }) + const agentB = ctx.agentLoop.create(AgentId('b'), { model: 'mock-b' }) + agentA.send([{ type: 'text', text: 'go' }]) + agentB.send([{ type: 'text', text: 'go' }]) + await Promise.all([waitForIdle(ctx, agentA), waitForIdle(ctx, agentB)]) + + expect(reminders(agentA)).toHaveLength(0) // 2 repeats < 3, despite B's 3 in the same registry + expect(reminders(agentB)).toHaveLength(1) + }) + + it('a new user prompt resets the chain', async () => { + const ctx = await harness() + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + toolCallResponse('c2', 'probe', { q: 1 }), + textResponse('turn one done'), + toolCallResponse('c3', 'probe', { q: 1 }), // without the reset this would be the 3rd + textResponse('turn two done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + agent.send([{ type: 'text', text: 'again' }]) + await waitForIdle(ctx, agent) + + expect(reminders(agent)).toHaveLength(0) + }) + + it('drops an agent chain on disposal', async () => { + const ctx = await harness({ thresholds: [2] }) + ctx.llm.registerAdapter(['mock'], new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + textResponse('done'), + toolCallResponse('c2', 'probe', { q: 1 }), // same id, fresh agent: count 1, not 2 + textResponse('done'), + ])) + // Loop agents are torn down by disposing the scope that created them + // (the loop.spec pattern): a child plugin fiber owns `first`. + let first!: ReactLoopAgent + const fiber = await ctx.plugin(Object.assign((inner: Context) => { + first = inner.agentLoop.create(AgentId('reused'), { model: 'mock' }) + }, { inject: ['agentLoop'] })) + first.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, first) + await fiber.dispose() + await first.done + + const second = ctx.agentLoop.create(AgentId('reused'), { model: 'mock' }) + second.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, second) + + expect(reminders(second)).toHaveLength(0) + }) + + it('counts denied calls: hammering a denied tool still draws the reminder', async () => { + const ctx = await harness({ thresholds: [2] }) + ctx.on('tools/pre-execute', async () => ({ kind: 'deny' as const, reason: 'sealed' })) + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + toolCallResponse('c2', 'probe', { q: 1 }), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(reminders(agent)).toHaveLength(1) + }) + + it('ignores direct executes with no agent (they neither crash nor advance any chain)', async () => { + const ctx = await harness({ thresholds: [2] }) + const direct = await ctx.tools.execute({ callId: CallId('d1'), name: 'probe', arguments: { q: 1 } }) + expect(direct.isError).toBe(false) + + ctx.llm.registerAdapter(['mock'], new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), // if the direct call had counted, this would be #2 + textResponse('done'), + ])) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + expect(reminders(agent)).toHaveLength(0) + }) +}) + +describe('fold onto the downstream decision', () => { + it('folds the reminder onto a downstream block and keeps its feedback', async () => { + const ctx = await harness({ thresholds: [2] }) + ctx.on('tools/post-execute', async () => ({ + kind: 'block' as const, + feedback: [{ type: 'text' as const, text: 'nope' }], + additionalContext: { content: [{ type: 'text' as const, text: 'downstream-ctx' }], source: { kind: 'plugin' as const, plugin: 'test' } }, + })) + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + toolCallResponse('c2', 'probe', { q: 1 }), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(2) + // Call 1: below threshold — the downstream context passes through untouched. + expect(found[0]!.text).toBe('downstream-ctx') + expect(found[0]!.source).toEqual({ kind: 'plugin', plugin: 'test' }) + // Call 2: reminder folded in front, single merged context, the guard's source. + expect(found[1]!.text).toContain('repeating the exact same tool call') + expect(found[1]!.text).toContain('|downstream-ctx') + expect(found[1]!.source).toEqual(GUARD_SOURCE) + // The block's feedback reached the tool result unchanged. + const results = [...agent.session.events].filter((e): e is SessionEvent<'tool/result'> => e.type === 'tool/result') + expect(results.every(r => r.data.isError)).toBe(true) + expect(results[1]!.data.content).toEqual([{ type: 'text', text: 'nope' }]) + }) + + it('preserves a downstream accept content replacement while folding', async () => { + const ctx = await harness({ thresholds: [2] }) + ctx.on('tools/post-execute', async () => ({ + kind: 'accept' as const, + content: [{ type: 'text' as const, text: 'replaced' }], + })) + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { q: 1 }), + toolCallResponse('c2', 'probe', { q: 1 }), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(1) + expect(found[0]!.text).toContain('repeating the exact same tool call') + const results = [...agent.session.events].filter((e): e is SessionEvent<'tool/result'> => e.type === 'tool/result') + expect(results[1]!.data.content).toEqual([{ type: 'text', text: 'replaced' }]) + }) +}) + +describe('config validation fails loud', () => { + async function spine(): Promise { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + return ctx + } + + it('rejects an empty thresholds list', async () => { + const ctx = await spine() + await expect(ctx.plugin(RepeatToolGuard, { thresholds: [] })).rejects.toThrow(/must not be empty/) + }) + + it('rejects a threshold below 2', async () => { + const ctx = await spine() + await expect(ctx.plugin(RepeatToolGuard, { thresholds: [1, 3] })).rejects.toThrow(/integer >= 2/) + }) + + it('rejects a non-integer threshold', async () => { + const ctx = await spine() + await expect(ctx.plugin(RepeatToolGuard, { thresholds: [2.5] })).rejects.toThrow(/integer >= 2/) + }) + + it('rejects duplicate thresholds', async () => { + const ctx = await spine() + await expect(ctx.plugin(RepeatToolGuard, { thresholds: [3, 3] })).rejects.toThrow(/duplicates/) + }) +}) diff --git a/packages/guard/repeat-tool-guard/tsconfig.json b/packages/guard/repeat-tool-guard/tsconfig.json new file mode 100644 index 0000000000..66439bcd5f --- /dev/null +++ b/packages/guard/repeat-tool-guard/tsconfig.json @@ -0,0 +1,30 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../core/tools" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../llm/llm" + } + ] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9856e99e95..23de7eac3d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -381,6 +381,34 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/guard/repeat-tool-guard: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-agent-loop': + specifier: workspace:^ + version: link:../../core/agent-loop + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/hooks/hook-protocol: devDependencies: '@deepseek-ai/dsh-bash': diff --git a/tsconfig.base.json b/tsconfig.base.json index 40e4dbe728..152a0064ac 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -45,6 +45,7 @@ "./packages/bash/*/src", "./packages/fs/*/src", "./packages/compact/*/src", + "./packages/guard/*/src", "./packages/subagent/*/src", "./packages/web/*/src", "./packages/todo/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index 96d87c01e9..6bf35060a0 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -53,6 +53,7 @@ { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/todo/tool-todo" }, + { "path": "./packages/guard/repeat-tool-guard" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" } diff --git a/tsconfig.json b/tsconfig.json index ff737baf04..5a0c19acb9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -64,6 +64,7 @@ { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/todo/tool-todo" }, + { "path": "./packages/guard/repeat-tool-guard" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" } From 93d5e4c5607db8b53ad033ee46b4ecc2dcabd729 Mon Sep 17 00:00:00 2001 From: kingwl Date: Wed, 8 Jul 2026 14:24:20 +0800 Subject: [PATCH 047/119] test(acp-snapshot): replace the authored-implies-override guard with an explicit overridden flag --- .../testing/2026-06-19-acp-snapshot-tests.md | 2 +- packages/support/acp-snapshot/src/suite.ts | 33 ++++++++++++------- .../support/acp-snapshot/tests/suite.spec.ts | 4 +-- 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md b/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md index 6e73d5d333..ae5ea96f83 100644 --- a/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md +++ b/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md @@ -68,7 +68,7 @@ The replay plugin lives in its own package, `@deepseek-ai/dsh-llm-replay` (`pack ### Two subcommands, replay in the default gate -`pnpm run test:snapshot` runs replay (keyless) and is composed into the default `pnpm run test` gate so every PR gets the regression check (the main `vitest.config.ts` include stays narrow; the gate is `test && test:snapshot`). `pnpm run test:snapshot:record` requires `DEEPSEEK_API_KEY` (loaded from repo `.env` first), hits the real API, harvests the produced `session.jsonl` (the replay source AND the expected-log artifact), and `--update`s the stdout golden in one pass. Both forward a scenario filter. A missing fixture in replay **fails loud** with a "record first" message rather than self-skipping (the e2e self-skip rule is a CI-secret accommodation, not appropriate here — a committed-fixture test that silently vanishes is a coverage hole). A no-model scenario's `session.jsonl` simply has no `assistant/chunk` events (empty derived script); fail-loud still applies if a model call happens with no entry. An orphan-fixture guard test fails on a golden/fixture not referenced by any scenario (Vitest does not prune orphaned raw goldens), and a per-kind required-fixture guard asserts each scenario ships exactly the files its kind needs (`input.json` + `stdout.golden.jsonl` + `session.jsonl` for ALL scenarios — the harness passes `/session.jsonl` to `llm-replay` unconditionally, so even a no-model scenario needs its header-only fixture or `loadReplayScript()` fails; `replay.override.json` additionally for authored model scenarios). +`pnpm run test:snapshot` runs replay (keyless) and is composed into the default `pnpm run test` gate so every PR gets the regression check (the main `vitest.config.ts` include stays narrow; the gate is `test && test:snapshot`). `pnpm run test:snapshot:record` requires `DEEPSEEK_API_KEY` (loaded from repo `.env` first), hits the real API, harvests the produced `session.jsonl` (the replay source AND the expected-log artifact), and `--update`s the stdout golden in one pass. Both forward a scenario filter. A missing fixture in replay **fails loud** with a "record first" message rather than self-skipping (the e2e self-skip rule is a CI-secret accommodation, not appropriate here — a committed-fixture test that silently vanishes is a coverage hole). A no-model scenario's `session.jsonl` simply has no `assistant/chunk` events (empty derived script); fail-loud still applies if a model call happens with no entry. An orphan-fixture guard test fails on a golden/fixture not referenced by any scenario (Vitest does not prune orphaned raw goldens), and a per-kind required-fixture guard asserts each scenario ships exactly the files its kind needs (`input.json` + `stdout.golden.jsonl` + `session.jsonl` for ALL scenarios — the harness passes `/session.jsonl` to `llm-replay` unconditionally, so even a no-model scenario needs its header-only fixture or `loadReplayScript()` fails; `replay.override.json` exactly for the scenarios whose table entry sets `overridden` — required with the flag, forbidden without it, because the harness forwards the sidecar purely on file existence and an unregistered stray would silently replace the derived script). ## Alternatives considered diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts index 14a4df54da..9718fc7d5e 100644 --- a/packages/support/acp-snapshot/src/suite.ts +++ b/packages/support/acp-snapshot/src/suite.ts @@ -52,12 +52,22 @@ export interface Scenario { /** * Whether `test:snapshot:record` regenerates this scenario's `session.jsonl` * from the LIVE API. `recorded` scenarios are model-driven and reproducible; - * `authored` scenarios (a hand-written `replay.override.json` sidecar drives - * replay — e.g. a provider error or a cancel, which the live API can't be - * coaxed into deterministically — or a deterministic hook scenario whose - * derived empty script needs no sidecar) are NEVER re-recorded. + * `authored` scenarios (fixtures hand-written or hand-harvested — e.g. a + * provider error or a cancel the live API can't be coaxed into + * deterministically, a deterministic hook scenario, or a scripted repetition + * a live model won't reproduce) are NEVER re-recorded. */ recorded: boolean + /** + * Whether replay is driven by a hand-written `replay.override.json` sidecar + * (a `ReplayEntry[]` that REPLACES the script derived from `session.jsonl`) + * — the throw/hang cases chunks cannot express. The fixture guard requires + * the sidecar exactly when this is set: the harness forwards the file purely + * on existence, so an unregistered stray sidecar would silently replace the + * derived script — the guard fails loud on either mismatch. Defaults to + * false (replay derives from the fixture's `assistant/chunk` events). + */ + overridden?: boolean /** * How many SUBAGENT child sessions this scenario records beyond the top-level * one (0 for a single-session scenario). Each child rides in a sibling fixture @@ -317,17 +327,18 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { // throws "fixture not found" when it is absent and no override replaces it. // A no-model scenario ships a header-only `session.jsonl` (it derives to an // empty script — no model call is made); a model scenario's fixture also - // doubles as the expected-log artifact the run is diffed against. An authored - // (non-`recorded`) model scenario additionally ships a `replay.override.json` - // sidecar for the throw/hang cases a derived script cannot express. - for (const { name, hasModelTurn, recorded, childSessions } of scenarios) { + // doubles as the expected-log artifact the run is diffed against. The + // `replay.override.json` sidecar is matched BOTH ways against the table's + // `overridden` flag: required when set, forbidden when not — the harness + // forwards the file purely on existence, so an unregistered stray sidecar + // would silently replace the derived script. + for (const { name, overridden, childSessions } of scenarios) { const dir = join(snapshotsDir, name) expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true) expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true) expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true) - if (hasModelTurn && !recorded) { - expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json`).toBe(true) - } + expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``) + .toBe(overridden === true) // A nested-agent scenario ships one child fixture per recorded subagent // session (`session.1.jsonl` …), the replay source for that child session. for (const childFixture of childFixturePaths(dir, childSessions ?? 0)) { diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index 0bc15aeec2..e14f525b30 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -39,14 +39,14 @@ const REPLAY_SCENARIOS: Scenario[] = [ { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1 }, { name: 'no-model', hasModelTurn: false, recorded: false }, { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false }, - { name: 'authored-error', hasModelTurn: true, recorded: false }, + { name: 'authored-error', hasModelTurn: true, recorded: false, overridden: true }, ] const RECORD_SCENARIOS: Scenario[] = [ { name: 'rec-pin', hasModelTurn: true, recorded: true, pinsHeader: true }, { name: 'rec-child', hasModelTurn: true, recorded: true, childSessions: 1 }, // recorded:false in record mode → registered but skipped (never re-recorded). - { name: 'rec-skip', hasModelTurn: true, recorded: false }, + { name: 'rec-skip', hasModelTurn: true, recorded: false, overridden: true }, ] // Record mode mutates its snapshots dir, so run it on a throwaway copy — From a0e39db3b64ee6255089c6e498022132abdfdc86 Mon Sep 17 00:00:00 2001 From: kingwl Date: Wed, 8 Jul 2026 14:24:20 +0800 Subject: [PATCH 048/119] test(acp-snapshot): add the repeat-tool-guard reminder scenario --- examples/acp-agent/README.md | 2 +- examples/acp-agent/composition.md | 3 + examples/acp-agent/cordis.yml | 8 +++ examples/acp-agent/tests/acp.snapshot.ts | 9 ++- .../snapshots/repeat-tool-guard/input.json | 7 ++ .../snapshots/repeat-tool-guard/session.jsonl | 70 +++++++++++++++++++ .../repeat-tool-guard/stdout.golden.jsonl | 19 +++++ 7 files changed, 115 insertions(+), 3 deletions(-) create mode 100644 examples/acp-agent/tests/snapshots/repeat-tool-guard/input.json create mode 100644 examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl create mode 100644 examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.golden.jsonl diff --git a/examples/acp-agent/README.md b/examples/acp-agent/README.md index 58a5984301..a1f6e818ab 100644 --- a/examples/acp-agent/README.md +++ b/examples/acp-agent/README.md @@ -6,7 +6,7 @@ The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)* pnpm run demo:acp # needs DEEPSEEK_API_KEY (repo-root .env or env) ``` -This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, and the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC. +This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC. ## stdout is the protocol diff --git a/examples/acp-agent/composition.md b/examples/acp-agent/composition.md index 2644a2b112..7fd5e25875 100644 --- a/examples/acp-agent/composition.md +++ b/examples/acp-agent/composition.md @@ -33,6 +33,8 @@ flowchart LR cfg --> plugin_acp_tool_subagent_fork plugin_acp_tool_todo["tool-todo
@deepseek-ai/dsh-tool-todo"] cfg --> plugin_acp_tool_todo + plugin_acp_repeat_tool_guard["repeat-tool-guard
@deepseek-ai/dsh-repeat-tool-guard"] + cfg --> plugin_acp_repeat_tool_guard plugin_acp_fs_local["fs-local
@deepseek-ai/dsh-fs-local"] cfg --> plugin_acp_fs_local plugin_acp_fs_policy["fs-policy
@deepseek-ai/dsh-fs-policy"] @@ -56,6 +58,7 @@ flowchart LR | `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` | | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` | | `tool-todo` | `@deepseek-ai/dsh-tool-todo` | +| `repeat-tool-guard` | `@deepseek-ai/dsh-repeat-tool-guard` | | `fs-local` | `@deepseek-ai/dsh-fs-local` | | `fs-policy` | `@deepseek-ai/dsh-fs-policy` | | `tool-fs` | `@deepseek-ai/dsh-tool-fs` | diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml index 83ac07ce55..af2da25b86 100644 --- a/examples/acp-agent/cordis.yml +++ b/examples/acp-agent/cordis.yml @@ -86,6 +86,14 @@ - id: tool-todo name: '@deepseek-ai/dsh-tool-todo' +# The repeat-tool-call guard: advisory reminders (injected context, never a +# block) when the model re-issues the same tool call with identical arguments; +# defaults [3, 5, 8]. Loaded here so the snapshot tier exercises the reminder +# transcript (the repeat-tool-guard scenario) — no other scenario repeats a +# call three times, so it is inert everywhere else. +- id: repeat-tool-guard + name: '@deepseek-ai/dsh-repeat-tool-guard' + # Filesystem capability stack: local provider, read-before-write/edit policy # gate, then the model-facing read/write/edit tools. Relative filesystem paths # resolve from the server launch cwd; the documented Zed setup launches this diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index b864189a61..647a37e9df 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -39,8 +39,13 @@ const SCENARIOS: Scenario[] = [ { name: 'fs-read-window', hasModelTurn: true, recorded: true }, { name: 'fs-policy-reject', hasModelTurn: true, recorded: true }, { name: 'multi-turn', hasModelTurn: true, recorded: true }, - { name: 'error-finish', hasModelTurn: true, recorded: false }, - { name: 'cancel', hasModelTurn: true, recorded: false }, + { name: 'error-finish', hasModelTurn: true, recorded: false, overridden: true }, + // Keyless, authored (like error-finish/cancel): deterministically forcing a + // LIVE model to repeat one call three times is not a stable recording, so + // the fixture scripts five identical todo_write calls and pins BOTH reminder + // tiers (gentle at 3, detailed at 5) as context/message in transcript and log. + { name: 'repeat-tool-guard', hasModelTurn: true, recorded: false }, + { name: 'cancel', hasModelTurn: true, recorded: false, overridden: true }, { name: 'subagent-spawn', hasModelTurn: true, recorded: true, childSessions: 1 }, { name: 'subagent-multi', hasModelTurn: true, recorded: true, childSessions: 2 }, { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 }, diff --git a/examples/acp-agent/tests/snapshots/repeat-tool-guard/input.json b/examples/acp-agent/tests/snapshots/repeat-tool-guard/input.json new file mode 100644 index 0000000000..9d2203ed57 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/repeat-tool-guard/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Write the todo list 'watch the kettle boil' five times in a row without changing it, then reply DONE." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl b/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl new file mode 100644 index 0000000000..7e50e71b3b --- /dev/null +++ b/examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl @@ -0,0 +1,70 @@ +{"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":"Write the todo list 'watch the kettle boil' five times in a row without changing it, 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":{"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_1","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}} +{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}} +{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"} +{"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}} +{"type":"todo/write","seq":11,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}} +{"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"callId":"call_1","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} +{"type":"step/end","seq":13,"time":0,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":14,"time":0,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_2","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}} +{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}} +{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"} +{"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}} +{"type":"todo/write","seq":22,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}} +{"type":"tool/result","seq":23,"time":0,"data":{"turn":1,"step":2,"callId":"call_2","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"} +{"type":"step/end","seq":24,"time":0,"data":{"turn":1,"step":2}} +{"type":"step/start","seq":25,"time":0,"data":{"turn":1,"step":3}} +{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"call_3","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}} +{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}} +{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":30,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":31,"time":0,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[26,27,28,29,30],"surfaceOp":"append"} +{"type":"tool/call","seq":32,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}} +{"type":"todo/write","seq":33,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}} +{"type":"tool/result","seq":34,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[32],"surfaceOp":"append"} +{"type":"context/message","seq":35,"time":0,"data":{"content":[{"type":"text","text":"You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"} +{"type":"step/end","seq":36,"time":0,"data":{"turn":1,"step":3}} +{"type":"step/start","seq":37,"time":0,"data":{"turn":1,"step":4}} +{"type":"assistant/chunk","seq":38,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"call_4","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}} +{"type":"assistant/chunk","seq":40,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}} +{"type":"assistant/chunk","seq":41,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":42,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":43,"time":0,"data":{"turn":1,"step":4,"content":[{"type":"tool-call","id":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[38,39,40,41,42],"surfaceOp":"append"} +{"type":"tool/call","seq":44,"time":0,"data":{"turn":1,"step":4,"callId":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}} +{"type":"todo/write","seq":45,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}} +{"type":"tool/result","seq":46,"time":0,"data":{"turn":1,"step":4,"callId":"call_4","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[44],"surfaceOp":"append"} +{"type":"step/end","seq":47,"time":0,"data":{"turn":1,"step":4}} +{"type":"step/start","seq":48,"time":0,"data":{"turn":1,"step":5}} +{"type":"assistant/chunk","seq":49,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":50,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"call_5","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}} +{"type":"assistant/chunk","seq":51,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}} +{"type":"assistant/chunk","seq":52,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":53,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":54,"time":0,"data":{"turn":1,"step":5,"content":[{"type":"tool-call","id":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[49,50,51,52,53],"surfaceOp":"append"} +{"type":"tool/call","seq":55,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}} +{"type":"todo/write","seq":56,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}} +{"type":"tool/result","seq":57,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[55],"surfaceOp":"append"} +{"type":"context/message","seq":58,"time":0,"data":{"content":[{"type":"text","text":"Repeated tool call detected:\n- tool: todo_write\n- consecutive_calls: 5\n- arguments: {\"todos\":[{\"content\":\"watch the kettle boil\",\"status\":\"in_progress\"}]}\nThe repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"} +{"type":"step/end","seq":59,"time":0,"data":{"turn":1,"step":5}} +{"type":"step/start","seq":60,"time":0,"data":{"turn":1,"step":6}} +{"type":"assistant/chunk","seq":61,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","seq":62,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"DONE."}}} +{"type":"assistant/chunk","seq":63,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE."}}}} +{"type":"assistant/chunk","seq":64,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":3}}}} +{"type":"assistant/chunk","seq":65,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":66,"time":0,"data":{"turn":1,"step":6,"content":[{"type":"text","text":"DONE."}],"usage":{"inputTokens":10,"outputTokens":3}},"sourceEventSeqs":[61,62,63,64,65],"surfaceOp":"append"} +{"type":"step/end","seq":67,"time":0,"data":{"turn":1,"step":6}} +{"type":"turn/end","seq":68,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.golden.jsonl new file mode 100644 index 0000000000..a3ae2e3870 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.golden.jsonl @@ -0,0 +1,19 @@ +{"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}}"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_1","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_1","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_2","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_2","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_3","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_3","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_4","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_4","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_5","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_5","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}} +{"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"}} From a58196307020c685765913cc9b4b04ba6ba16329 Mon Sep 17 00:00:00 2001 From: kingwl Date: Wed, 8 Jul 2026 14:24:20 +0800 Subject: [PATCH 049/119] docs(rfc): promote the repeat-tool-guard RFC to implemented --- docs/rfc/INDEX.md | 2 +- .../feature/2026-07-08-repeat-tool-guard.md | 47 ++++++++----------- 2 files changed, 21 insertions(+), 28 deletions(-) rename docs/rfc/{proposed => implemented}/feature/2026-07-08-repeat-tool-guard.md (51%) diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 3af42ef70e..ea49c1ff3f 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -13,7 +13,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Optional Code Mode — model writes TypeScript against an SDK of all tools](proposed/feature/2026-06-15-optional-code-mode.md) | 2026-06-15 | | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 | | [Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)](proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md) | 2026-07-07 | -| [Repeat-tool-call guard plugin](proposed/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 | ### Simplification @@ -63,6 +62,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 | | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 | | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 | +| [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 | ### Simplification diff --git a/docs/rfc/proposed/feature/2026-07-08-repeat-tool-guard.md b/docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md similarity index 51% rename from docs/rfc/proposed/feature/2026-07-08-repeat-tool-guard.md rename to docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md index 19193ea583..e0e9c28b5c 100644 --- a/docs/rfc/proposed/feature/2026-07-08-repeat-tool-guard.md +++ b/docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md @@ -1,20 +1,20 @@ # RFC: Repeat-tool-call guard plugin -Status: proposed +Status: implemented ## Problem A model stuck in a loop re-issues the same tool call with byte-identical arguments — re-running a failing grep, re-reading an unchanged file, polling a command that already gave its answer — and each round trip burns tokens, wall-clock, and (for paid APIs) money without adding information. The harness has nothing that notices: the loop has no step budget, no plugin tracks call repetition, and the model only escapes when it happens to vary its own behavior. The failure mode is real and cheap to detect — [pi-repeat-tool-guard](https://github.com/Kingwl/pi-repeat-tool-guard) ships exactly this as a pi coding-agent extension: count consecutive identical calls and, past a threshold, append a `` telling the model to stop repeating itself and change course. -The harness already has every seam the pi extension uses, and better ones: [the interception-seams RFC](../../implemented/feature/2026-06-30-interception-seams.md) gives `tools/post-execute` a sanctioned way to attach model-facing context to a finished call, the loop buffers and injects that context with call/result adjacency preserved, and injected context is a logged `context/message` — so a native guard satisfies the model-visible ⟺ logged rule with no new session event. What is missing is only the plugin itself. +The harness already has every seam the pi extension uses, and better ones: [the interception-seams RFC](2026-06-30-interception-seams.md) gives `tools/post-execute` a sanctioned way to attach model-facing context to a finished call, the loop buffers and injects that context with call/result adjacency preserved, and injected context is a logged `context/message` — so a native guard satisfies the model-visible ⟺ logged rule with no new session event. What was missing was only the plugin itself. -## Proposal +## Decision The guard is a loop-hygiene plugin, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The purpose is to break unproductive loops within a few wasted steps instead of letting them run to the turn's natural end — while leaving the decision (retry differently, gather more evidence, or finish) entirely with the model, so a legitimately repeated call is delayed by nothing and blocked by nothing. -The shape: one new leaf plugin package, `@deepseek-ai/dsh-repeat-tool-guard` at `packages/guard/repeat-tool-guard/`, opening a `guard/` group for loop-hygiene plugins (single-package groups have precedent: [the todo-write RFC](../../implemented/feature/2026-06-29-todo-write-tool.md) shipped `todo/tool-todo`). The plugin registers three listeners via `ctx.effect()` and holds all state in plugin-local maps keyed by `AgentId` — the tool registry is a context-level singleton whose waterfalls interleave every agent's calls (subagents run on the same context), so per-agent keying is correctness, not polish. +The plugin is `@deepseek-ai/dsh-repeat-tool-guard` at `packages/guard/repeat-tool-guard/`, opening the `guard/` group for loop-hygiene plugins (single-package groups have precedent: [the todo-write RFC](2026-06-29-todo-write-tool.md) shipped `todo/tool-todo`). It registers three listeners and holds all state in plugin-local maps keyed by `AgentId` — the tool registry is a context-level singleton whose waterfalls interleave every agent's calls (subagents run on the same context), so per-agent keying is correctness, not polish. -- **`tools/post-execute` (waterfall)** — the one detection point. The listener receives `(exec, result)` together, so counting and reminder delivery need no cross-event pending map (the pi extension needs one only because its `tool_call`/`tool_result` hooks are separate events). It always delegates via `next()` and, when a threshold is hit, folds a reminder onto the downstream decision's `additionalContext` — the observe-and-enrich posture [the hooks bridges](../../implemented/feature/2026-06-30-hook-bridges.md) already use, honoring the waterfall contract. Counting happens here rather than in `tools/pre-execute` because post-execute also runs for denied calls (`ToolRegistry.execute` routes a deny through the same pipeline), and a model hammering a denied call is exactly the loop worth breaking. +- **`tools/post-execute` (waterfall)** — the one detection point. The listener receives `(exec, result)` together, so counting and reminder delivery need no cross-event pending map (the pi extension needs one only because its `tool_call`/`tool_result` hooks are separate events). It always delegates via `next()` and, when a threshold is hit, folds a reminder onto the downstream decision's `additionalContext` — the observe-and-enrich posture [the hooks bridges](2026-06-30-hook-bridges.md) already use, honoring the waterfall contract. Counting happens here rather than in `tools/pre-execute` because post-execute also runs for denied calls (`ToolRegistry.execute` routes a deny through the same pipeline), and a model hammering a denied call is exactly the loop worth breaking. - **`agent/prompt-submit` (waterfall)** — pure reset hook: delegate via `next()`, clear the submitting agent's chain. A user interjection changes the context; repetition across it is not a loop. - **`agent/status` (emit)** — on `disposed`, drop the agent's state, bounding the maps over harness lifetime. @@ -22,14 +22,14 @@ The shape: one new leaf plugin package, `@deepseek-ai/dsh-repeat-tool-guard` at The chain key is `(tool name, canonical arguments)`; a call identical to the previous tracked call increments the agent's consecutive counter, a different tracked call resets it to 1. Canonicalization is a deep key-sort plus `JSON.stringify`: `ToolExecution.arguments` is by construction the loop's `JSON.parse` output (or the raw string fallback for malformed argument JSON, which is itself a comparable value), so the pi original's bigint/circular/`undefined` handling has no inputs here and is deliberately dropped. -Two deliberate rules, both documented in the package README because they are behavior a reader would otherwise guess at: +Two deliberate rules, both documented in [the package README](../../../../packages/guard/repeat-tool-guard/README.md) because they are behavior a reader would otherwise guess at: - **Untracked calls are transparent to the chain.** A call excluded by `include`/`exclude` neither increments nor resets the counter, so `grep X → todo_write → grep X` still counts as two consecutive `grep X` when `todo_write` is excluded. This is what makes exclusion useful — bookkeeping tools interleaved into a loop must not launder it — and it is the pi extension's (undocumented) semantics, kept on purpose and written down. -- **Calls without an agent are ignored.** A direct `ctx.tools.execute()` caller (tests, future non-loop consumers) has no model to remind and no `AgentId` to key on. +- **Calls without an agent are ignored.** A direct `ctx.tools.execute()` caller (tests, non-loop consumers) has no model to remind and no `AgentId` to key on. ### Reminder delivery -Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}` — the label is load-bearing per `HookContext`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit, and the loop already appends buffered context as `context/message`(s) after the step's results, which the session renders as the tagged synthetic-user envelope and derived history replays. Thresholds escalate: the first configured threshold gets a short "you are repeating yourself, analyze the previous result" nudge; each later threshold gets the detailed form naming the tool, the repeat count, and the canonical arguments, and stating that the calls made no progress. The pi original hardcodes the gentle text to the literal count 3; the guard keys it to `thresholds[0]`, fixing that bug in the port. When the downstream decision already carries `additionalContext` (a hook bridge on the same call), the guard folds content following the shared-merge precedent in `dsh-hook-protocol`. +Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}` — the label is load-bearing per `HookContext`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit, and the loop appends buffered context as `context/message`(s) after the step's results, which the session renders as the tagged synthetic-user envelope and derived history replays. Thresholds escalate: the first configured threshold gets a short "you are repeating yourself, analyze the previous result" nudge; each later threshold gets the detailed form naming the tool, the repeat count, and the canonical arguments, and stating that the calls made no progress. The pi original hardcodes the gentle text to the literal count 3; the guard keys it to `thresholds[0]`, fixing that bug in the port. When the downstream decision already carries `additionalContext` (a hook bridge on the same call), the guard concatenates content under its own `source` — a `HookContext` holds one `MessageSource`, and `source.kind` is what framing depends on. ### Config @@ -44,36 +44,29 @@ Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-too `thresholds` is validated at load and throws on an empty list, a non-integer, a value below 2, or a duplicate — misconfiguration fails loud, replacing the pi original's silent fall-back to defaults. `include`/`exclude` entries support `*` wildcards. Patterns are predicates over whatever tools exist at call time, not references to a registry entry, so an entry matching no currently registered tool is NOT an error — unlike `toolOrder`'s referent check, `exclude: [mcp_*]` must stay valid in a deployment that loads no MCP tools. -### Testing +## Testing -Coverage named at plan time, per tier: **unit** — counting/reset semantics (identical, different-tracked, untracked-transparent, prompt-submit reset, disposal cleanup, per-agent isolation), canonicalization, threshold escalation including the `thresholds[0]` gentle-text rule, config fail-loud cases, and the fold-onto-downstream-decision path, to per-file 100% like every `packages/*/*/src` file. **Snapshot** — one scripted-replay scenario where the model repeats a call to threshold and the reminder `context/message` appears in the transcript, pinning the model-visible text and its envelope (this is a transcript-surface change; the ACP snapshot suite is the tier that owns it). **e2e** — none: the plugin is provider-independent and deterministic, and forcing a live model to repeat a call three times is not a stable test; the seam contracts it relies on are already e2e-covered by their owners. +**Unit** — the suite drives a real agent loop against a scripted mock adapter (no network) and covers, at per-file 100%: counting/reset semantics (identical, different-tracked, untracked-transparent, prompt-submit reset, disposal cleanup, per-agent isolation), canonicalization (deep key-order insensitivity), threshold escalation including the `thresholds[0]` gentle-text rule, denied-call counting, no-agent transparency, wildcard escaping, config fail-loud cases, and both fold-onto-downstream paths (block and accept-with-replacement). **Snapshot** — the `repeat-tool-guard` scenario in the acp-agent example suite scripts five identical `todo_write` calls and pins both reminder tiers (gentle at the third, detailed at the fifth) as `context/message`s in the ACP transcript and the session log; the guard is loaded in the example's live tree (`cordis.yml`), inert for every other scenario (none repeats a call three times). The scenario is authored keyless (like `error-finish`/`cancel`): deterministically forcing a live model to repeat one call three times is not a stable recording. **e2e** — none: the plugin is provider-independent and deterministic, and the seam contracts it relies on are e2e-covered by their owners. ## Alternatives considered - **Append the reminder into the tool result** (`accept` with replaced `content` — the pi extension's mechanism, which patches result content because that is the only channel its API offers) — rejected: it makes the logged `tool/result` lie about what the tool returned, and `additionalContext` exists precisely as the separate sanctioned channel for post-execute commentary, with loop-level buffering that preserves call/result adjacency. - **Count in `tools/pre-execute` with a pending-reminder map** (the pi two-phase shape) — rejected: post-execute alone sees `(exec, result)` together and also fires for denied calls, so one listener with no cross-event state covers strictly more attempts with less machinery. - **Escalate to `block` at the highest threshold** — rejected for the initial scope: a blocked call punishes legitimate identical repeats (polling a long-running terminal, re-checking a file the agent expects to change), and an advisory reminder keeps the model in control. Revisit with evidence; the decision shape (`PostToolDecision`) already supports it. -- **A per-deployment external hook via the CC/Codex bridges** (a `PostToolUse` script) — rejected as the answer: it works today for one deployment, but a shipped, unit-tested, `cordis.yml`-configurable plugin is the harness-native form, without per-call subprocess cost. +- **A per-deployment external hook via the CC/Codex bridges** (a `PostToolUse` script) — rejected as the answer: it works for one deployment, but a shipped, unit-tested, `cordis.yml`-configurable plugin is the harness-native form, without per-call subprocess cost. - **A loop-level step or repetition budget in `agent-loop`** — rejected: "plugins, not loop changes"; a hard step budget is a blunter, orthogonal control that would need its own proposal. - **Fuzzy/near-identical detection** (normalized paths, similar-but-not-equal arguments) — rejected: exact match after canonicalization is cheap, deterministic, and explainable to the model; similarity thresholds invite false positives and need evidence before they earn complexity. - **Placing the package in `core/`** — rejected: core is the product spine; a behavioral guard is an optional leaf plugin, and the `todo/` precedent is a small dedicated group per plugin family. -## Acceptance criteria +## Consequences -- `packages/guard/repeat-tool-guard/` exists, registers all listeners through `ctx.effect()`, and is loadable from a `cordis.yml` with the config above; the config catalog regenerates with its entry. -- Invalid `thresholds` (empty, non-integer, `< 2`, duplicate) throw at plugin load. -- Unit suite covers the semantics list above at per-file 100%; a snapshot scenario replays a threshold-crossing repetition and pins the reminder `context/message` in the transcript on macOS and Linux. -- The reminder is reconstructable from the session log alone (it is an ordinary `context/message` with a plugin source — no new session event). -- The package README opens with the plugin's purpose — an advisory loop-breaker that is not a model-facing tool, never blocks or rewrites a call, and only injects reminders — then documents the transparency rule, the per-agent keying, and the in-memory-only state; `doc-sync` is green. +- The reminder is advisory by design: idempotent polling patterns that repeat identical calls on purpose still receive nudges past the thresholds, and the pressure valves are config (`thresholds`, `exclude`) plus reminder text that explicitly allows finishing when enough evidence has been gathered. Each trigger costs reminder tokens on the next request; thresholds bound the frequency. +- Chain state is in-memory only: a session resumed from persistence starts with a fresh chain, so a loop spanning a resume draws its reminders later than a live one — accepted, the guard is a heuristic nudge, not a logged invariant, and persisting counter state would buy little for real complexity. +- When multiple post-execute producers attach context on one call, the fold concatenates under the guard's `source`; ordering between plugins follows listener registration order. The seam cannot represent mixed provenance — a limit inherited from `HookContext`, not owned by this plugin. +- Implementing the snapshot tier surfaced a hidden assumption in the suite kit: the fixture guard equated "authored model scenario" with "override-driven". The `Scenario` table now carries an explicit `overridden` flag, and the sidecar's presence is checked BOTH ways against it (an unregistered stray sidecar would silently replace the derived script) — the suite kit is stricter than it was before this plugin existed. -## Risks +## Deferred -- **False positives on legitimately repeated calls.** Idempotent polling patterns repeat identical calls on purpose; the reminder is advisory and thresholds/`exclude` are the pressure valves, but a badly tuned deployment adds noise to the transcript. Mitigation: conservative defaults and the reminder text explicitly allowing "finish the task if enough evidence has been gathered". -- **Reminder tokens are model-visible cost.** Each trigger appends a paragraph to the next request; thresholds bound the frequency, but a pathological agent can hit 3/5/8 repeatedly across different keys. -- **State is in-memory only.** A session resumed from persistence starts with a fresh chain, so a loop spanning a resume gets its reminders later than a live one — accepted: the guard is a heuristic nudge, not a logged invariant, and persisting counter state would buy little for real complexity. -- **Multiple context producers on one call.** When a hook bridge and the guard both attach `additionalContext`, ordering follows listener registration order; the fold keeps both, but the combined envelope's readability depends on merge behavior that this RFC inherits rather than owns. - -## Open questions - -- Should compaction reset chains? A compacted history changes what the model sees, but the repetition risk usually survives compaction; the initial answer is no. -- Should subagents inherit the parent's thresholds via config only, or ever share chain state? Per-agent isolation is the proposed default; sharing looks like a smell until a concrete case appears. +- Compaction does not reset chains: a compacted history changes what the model sees, but the repetition risk usually survives compaction. +- Escalating to `block` at a high threshold is not implemented; `PostToolDecision` already supports it if evidence arrives. +- Subagent chains stay isolated per agent; no sharing mechanism exists until a concrete case appears. From 534b1dc6d063149297311dcfc45b625638e3dbb1 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 14:37:42 +0800 Subject: [PATCH 050/119] refactor(timeout-policy): read budget from ToolDefinition, drop config The enforcer now reads ctx.tools.get(exec.name).timeoutMs instead of a free-text tool-name config map, so a mistyped name is impossible and the tools/change warn-once apparatus is gone. exec.name always resolves in the registry during dispatch, so there is no unknown-name path to warn about. --- packages/timeout/timeout-policy/README.md | 28 +-- packages/timeout/timeout-policy/src/index.ts | 119 +++------- .../tests/timeout-policy.spec.ts | 212 ++++-------------- 3 files changed, 82 insertions(+), 277 deletions(-) diff --git a/packages/timeout/timeout-policy/README.md b/packages/timeout/timeout-policy/README.md index bdf189ba7f..e637a658bf 100644 --- a/packages/timeout/timeout-policy/README.md +++ b/packages/timeout/timeout-policy/README.md @@ -1,47 +1,33 @@ # dsh-timeout-policy -Tool-call timeout policy: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for each configured tool and returns a structured `TOOL_TIMEOUT` result when that deadline wins. It is the reference `tools/execute` wrapper and the deployment-owned home for model-facing tool-call budgets (the timeout-library RFC's foreseen middleware). +Tool-call timeout enforcer: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for a tool declaring `timeoutMs` on its `ToolDefinition` and returns a structured `TOOL_TIMEOUT` result when that deadline wins. The budget is read from the tool's own declaration (`ToolDefinition.timeoutMs`, set by the owning tool plugin), so this plugin is **zero-config**. It is the reference `tools/execute` wrapper and the enforcement home for model-facing tool-call budgets (the timeout-library RFC's foreseen middleware). ## Plugin (namespace: `timeout-policy`) -A function/namespace plugin (`name` / `Config` / `apply`), not a service. It registers no tool and injects nothing — it consumes `ctx.tools`'s `tools/execute` waterfall, which the `dsh-tools` registry always provides. - -### Config - -Per-tool policy, keyed by the model-facing tool name. There is deliberately **no global default** (a global budget would silently start failing any tool that runs long once the plugin loads) and **no model-facing override** (timeout is deployment policy, not prompt semantics) in this version. +A function/namespace plugin (`name` / `inject` / `apply`), not a service. It registers no tool and takes no config — it consumes `ctx.tools`'s `tools/execute` waterfall (which the `dsh-tools` registry always provides) and reads each dispatched tool's declared `timeoutMs` from the registry (`ctx.tools.get(exec.name)`). ```yaml - id: timeout-policy name: '@deepseek-ai/dsh-timeout-policy' - config: - tools: - web_fetch: - timeoutMs: 30000 - web_search: - timeoutMs: 30000 ``` -| Key | Type | Meaning | -|---|---|---| -| `tools` | `Record` | Per-tool timeout policy; an unlisted tool gets no deadline. `timeoutMs` is required per configured tool and must be positive finite. | - -A configured tool name that never registers (a typo like `web_fech`, or a stale key) would silently apply the timeout to nothing. Because the tool set is dynamic (plugins register in `cordis.yml` order, HMR re-registers), this is not a load-time error — a real tool may register later. Instead, on every `tools/change` (and once at load) the plugin `logger.warn`s each configured name still absent from `ctx.tools`, warning each name at most once so a late registration silences it. This mirrors `dsh-tool-subagent`'s lifecycle-driven handling of a configured-but-unregistered provider name. +The per-tool budget is declared by the tool plugin (e.g. `dsh-tool-web`'s `fetchTimeoutMs`/`searchTimeoutMs` config, attached as `ToolDefinition.timeoutMs`); this plugin only enforces it, so a mistyped tool name is not possible. ### Behavior -For a **configured** tool the listener: +For a tool that **declares a `timeoutMs`** the listener: -1. Arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')` — one signal fusing the caller's abort with this plugin's timer (`@deepseek-ai/dsh-timeout`). +1. Reads the budget from the tool's own declaration in the registry (`ctx.tools.get(exec.name)?.timeoutMs`) and arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')` — one signal fusing the caller's abort with this plugin's timer (`@deepseek-ai/dsh-timeout`). 2. Swaps that derived signal onto `exec` for the downstream dispatch, then restores the caller's own signal afterward (cordis `next()` ignores passed arguments, so the wrapper mutates the shared `exec` in place; restoring keeps `tools/post-execute` seeing the caller's signal). 3. After dispatch, if `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches — this plugin's own timer fired — replaces the result with a structured `TOOL_TIMEOUT` tool result: `{ isError: true, error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, content: 'Error: tool call timed out after ms' }`. -An **unconfigured** tool delegates untouched (no deadline). +A tool that **declares no budget** delegates untouched (no deadline). The base `next()` of `tools/execute` is the registry's dispatch-with-normalization thunk, so when the timeout signal reaches a provider that throws its own upstream-abort error, dispatch first turns it into a normal error result, and this wrapper then replaces that with `TOOL_TIMEOUT`. That ordering is why the replacement is keyed off the signal (`timeoutOf`), not off the dispatched result's shape. ### Cooperative, not a hard kill -The derived signal only **notifies**; termination stays with the tool and the capability it forwards `exec.signal` to (the `dsh-timeout` library owns no kill). **"Configured" therefore means "cooperative with `exec.signal`"**: a tool that ignores the signal will not stop on timeout. A deployment must only configure tools that forward the signal to their implementation — the shipped `web_fetch`/`web_search` (which forward through `ctx.web` to providers) are the reference. `TOOL_TIMEOUT` needs no session event for reconstructability: it is the final model-facing `tool/result`, already logged by the loop. +The derived signal only **notifies**; termination stays with the tool and the capability it forwards `exec.signal` to (the `dsh-timeout` library owns no kill). **Declaring `timeoutMs` therefore means "cooperative with `exec.signal`"**: a tool that ignores the signal will not stop on timeout. Only signal-forwarding tools should declare it — the shipped `web_fetch`/`web_search` (which forward through `ctx.web` to providers) are the reference. `TOOL_TIMEOUT` needs no session event for reconstructability: it is the final model-facing `tool/result`, already logged by the loop. ### Composing with other `tools/execute` wrappers diff --git a/packages/timeout/timeout-policy/src/index.ts b/packages/timeout/timeout-policy/src/index.ts index b57091fe91..319de676a9 100644 --- a/packages/timeout/timeout-policy/src/index.ts +++ b/packages/timeout/timeout-policy/src/index.ts @@ -1,16 +1,20 @@ /** - * `@deepseek-ai/dsh-timeout-policy`: the tool-call timeout policy plugin. It - * registers ONE `tools/execute` around-dispatch listener that, for each - * configured tool, arms a per-call deadline on `exec.signal` and returns a - * structured `TOOL_TIMEOUT` result when that deadline wins. + * `@deepseek-ai/dsh-timeout-policy`: the tool-call timeout ENFORCER. It registers + * ONE `tools/execute` around-dispatch listener that, for a tool declaring a + * `timeoutMs` on its {@link ToolDefinition}, arms a per-call deadline on + * `exec.signal` and returns a structured `TOOL_TIMEOUT` result when that deadline + * wins. The budget is DECLARED by the tool (see `ToolDefinition.timeoutMs`, set + * by the owning tool plugin from its own config); this plugin only enforces it, + * so it is zero-config and there is no tool-name map to mistype. * * This is a COOPERATIVE deadline, not a hard kill: the derived signal only - * NOTIFIES. A configured tool (and the capability it forwards `exec.signal` to) - * must honor that signal and reach quiescence — the plugin never races the tool - * promise or terminates work itself (see the timeout-library RFC's rejection of - * `Promise.race`). "Configured" therefore MEANS "cooperative with `exec.signal`": - * a tool that ignores the signal will not stop on timeout, so a deployment must - * only list tools that forward it (the shipped web tools are the reference). + * NOTIFIES. A tool that declares `timeoutMs` (and the capability it forwards + * `exec.signal` to) must honor that signal and reach quiescence — the plugin + * never races the tool promise or terminates work itself (see the timeout-library + * RFC's rejection of `Promise.race`). Declaring `timeoutMs` therefore MEANS "this + * tool is cooperative with `exec.signal`": a tool that ignores the signal will + * not stop on timeout, so only signal-forwarding tools should declare it (the + * shipped web tools are the reference). * * Ownership of the `TOOL_TIMEOUT` code is entirely here: it is both the internal * {@link deadline} code (so {@link timeoutOf} scopes the classification to THIS @@ -29,7 +33,6 @@ */ import type { Context } from 'cordis' -import z from 'schemastery' import type { CallId } from '@deepseek-ai/dsh-llm' import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools' @@ -46,40 +49,9 @@ export const TOOL_TIMEOUT = 'TOOL_TIMEOUT' /** Cordis plugin name used by loader diagnostics. */ export const name = 'timeout-policy' -/** The tool registry seam this plugin wraps (`tools/execute`) and reads (`tools/change`, `get`). */ +/** The tool registry seam this plugin wraps (`tools/execute`) and reads (`get`). */ export const inject = ['tools'] -/** Per-tool timeout policy. `timeoutMs` is required and must be positive finite. */ -export interface ToolTimeoutPolicy { - /** The per-call cooperative deadline for this tool, in milliseconds. */ - timeoutMs: number -} - -/** - * Plugin config: per-tool timeout policy, keyed by the model-facing tool name. - * There is deliberately NO global default (a global budget would silently start - * failing any tool that happens to run long once the plugin loads) and NO model - * override (timeout is deployment policy, not prompt semantics) in this version. - */ -export interface Config { - /** Timeout policy per tool name; an unlisted tool gets no deadline from this plugin. */ - tools?: Record -} - -export const Config: z = z.object({ - tools: z.dict(z.object({ timeoutMs: z.number() })).default({}), -}) - -/** The shape after schemastery fills `tools` with its `{}` default. */ -type ResolvedConfig = Required - -/** A per-tool timeout must be a positive finite number (0 is not a "disable" value). */ -function assertPositiveFinite(toolName: string, value: number): void { - if (!Number.isFinite(value) || value <= 0) { - throw new Error(`timeout-policy: tools.${toolName}.timeoutMs must be a positive finite number`) - } -} - /** * The structured result substituted when this plugin's deadline wins. `content` * is the model-facing message; `error.code` is the same {@link TOOL_TIMEOUT} @@ -99,56 +71,23 @@ export function toolTimeoutResult(callId: CallId, timeoutMs: number): ToolExecut } /** - * Register the tool-call timeout policy. For a configured tool the listener arms - * a {@link deadline} on the caller's `exec.signal`, swaps it onto `exec` for the - * downstream dispatch (cordis `next()` ignores passed arguments, so a wrapper - * mutates the shared `exec` in place), restores the original signal afterward so - * `tools/post-execute` sees the caller's own signal, and replaces the result - * with {@link toolTimeoutResult} when its own timer fired. An unconfigured tool - * delegates untouched. + * Register the tool-call timeout enforcer. For a tool whose {@link ToolDefinition} + * declares `timeoutMs`, the listener arms a {@link deadline} on the caller's + * `exec.signal`, swaps it onto `exec` for the downstream dispatch (cordis + * `next()` ignores passed arguments, so a wrapper mutates the shared `exec` in + * place), restores the original signal afterward so `tools/post-execute` sees the + * caller's own signal, and replaces the result with {@link toolTimeoutResult} + * when its own timer fired. A tool that declares no budget delegates untouched. * - * A configured tool name that is never registered is almost always a typo or a - * stale config key (e.g. `web_fech` for `web_fetch`): the wrapper would then - * silently never fire for the intended tool. Since the tool set is dynamic - * (plugins register in `cordis.yml` order, and HMR re-registers), this cannot - * be a load-time hard error — a real tool may register later. Instead, mirror - * `dsh-tool-subagent`'s lifecycle-driven approach: on every `tools/change` (and - * once at apply), `logger.warn` each configured name still absent from the - * registry, warning each name at most once so a late registration silences it. + * The budget source is the tool's own declaration read from the registry + * (`ctx.tools.get(exec.name)?.timeoutMs`), NOT a plugin config map — `exec.name` + * is the tool being dispatched, so the lookup always resolves and there is no + * mistypable tool name and no unknown-name path to warn or throw about. */ -export function apply(ctx: Context, config: Config): void { - // schemastery (Config) has already filled `tools` with its {} default. - const resolved = config as ResolvedConfig - for (const [toolName, policy] of Object.entries(resolved.tools)) { - assertPositiveFinite(toolName, policy.timeoutMs) - } - - // Warn once per configured name that no registered tool matches, so a typo'd - // or stale config key is visible instead of silently applying to nothing. A - // name that later registers is dropped from `pending` before it is warned; a - // name that never registers is warned at most once (moved to `warned`), so a - // busy `tools/change` stream cannot spam the same key. - const pending = new Set(Object.keys(resolved.tools)) - const warned = new Set() - const warnUnknownToolNames = (): void => { - const nowUnknown: string[] = [] - for (const name of pending) { - if (ctx.tools.get(name) !== undefined) { pending.delete(name); continue } - if (!warned.has(name)) { warned.add(name); nowUnknown.push(name) } - } - if (nowUnknown.length > 0) { - ctx.logger.warn( - `timeout-policy: configured timeout for unregistered tool(s) ${nowUnknown.map(n => `"${n}"`).join(', ')} ` - + '— check for a typo or stale config key; the timeout applies to nothing until the tool registers.', - ) - } - } - ctx.on('tools/change', warnUnknownToolNames) - warnUnknownToolNames() - +export function apply(ctx: Context): void { ctx.on('tools/execute', async (exec, next): Promise => { - const timeoutMs = resolved.tools[exec.name]?.timeoutMs - // Unconfigured tool: no deadline, delegate unchanged. + const timeoutMs = ctx.tools.get(exec.name)?.timeoutMs + // A tool that declares no budget: no deadline, delegate unchanged. if (timeoutMs === undefined) return next() using d = deadline(exec.signal, timeoutMs, TOOL_TIMEOUT) diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts index 967e5659ed..ef5c52030f 100644 --- a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts +++ b/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts @@ -15,188 +15,86 @@ import ToolRegistry, { defineTool, type ToolExecution, type ToolExecutionResult, import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy' import { TOOL_TIMEOUT, toolTimeoutResult } from '@deepseek-ai/dsh-timeout-policy' -/** Mount the registry + the timeout-policy plugin with the given per-tool config. */ -async function setup(tools: Record = {}) { +/** Mount the registry + the zero-config timeout-policy enforcer. */ +async function setup() { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRegistry) - await ctx.plugin(timeoutPolicy, { tools }) + await ctx.plugin(timeoutPolicy) return ctx } -/** A fast tool: returns immediately, ignoring the signal. */ -const fastTool = defineTool({ - name: 'fast', - description: 'returns at once', - parameters: {}, - async execute() { return [{ type: 'text' as const, text: 'ok' }] }, -}) - /** A cooperative tool that settles ONLY when its exec.signal aborts (returns text). */ const cooperativeTool = defineTool({ - name: 'slow', - description: 'stops when aborted', - parameters: {}, + name: 'slow', description: 'stops when aborted', parameters: {}, timeoutMs: 100, execute(_args, exec): Promise<{ type: 'text'; text: string }[]> { const done = [{ type: 'text' as const, text: 'stopped cooperatively' }] if (exec.signal?.aborted) return Promise.resolve(done) - return new Promise((resolve) => { - exec.signal?.addEventListener('abort', () => { resolve(done) }) - }) + return new Promise((resolve) => { exec.signal?.addEventListener('abort', () => { resolve(done) }) }) }, }) /** A cooperative tool that THROWS its own upstream-abort error when aborted (web-provider shape). */ const abortThrowingTool = defineTool({ - name: 'aborter', - description: 'throws WEB_ABORTED when aborted', - parameters: {}, + name: 'aborter', description: 'throws WEB_ABORTED when aborted', parameters: {}, timeoutMs: 100, execute(_args, exec): Promise { if (exec.signal?.aborted) return Promise.reject(new HarnessError('web fetch aborted', 'WEB_ABORTED')) - return new Promise((_resolve, reject) => { - exec.signal?.addEventListener('abort', () => { reject(new HarnessError('web fetch aborted', 'WEB_ABORTED')) }) - }) + return new Promise((_resolve, reject) => { exec.signal?.addEventListener('abort', () => { reject(new HarnessError('web fetch aborted', 'WEB_ABORTED')) }) }) }, }) -describe('timeout-policy config validation', () => { - it('rejects a non-positive timeout at apply', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - await expect(ctx.plugin(timeoutPolicy, { tools: { web_fetch: { timeoutMs: 0 } } })) - .rejects.toThrow('tools.web_fetch.timeoutMs must be a positive finite number') - }) - - it('rejects a non-finite timeout at apply', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - await expect(ctx.plugin(timeoutPolicy, { tools: { web_fetch: { timeoutMs: Infinity } } })) - .rejects.toThrow('must be a positive finite number') - }) - - it('mounts with no config (empty tools default) and delegates every call', async () => { - const ctx = await setup() - ctx.tools.register(fastTool) - const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} }) - expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }) - }) -}) - -describe('timeout-policy unknown-tool-name diagnostics', () => { - it('warns for a configured tool name that is never registered (typo/stale key)', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) - // web_fech is a typo for web_fetch, and no tool by that name is registered. - await ctx.plugin(timeoutPolicy, { tools: { web_fech: { timeoutMs: 30_000 } } }) - expect(warn).toHaveBeenCalledTimes(1) - expect(warn.mock.calls[0]?.[0]).toContain('"web_fech"') - expect(warn.mock.calls[0]?.[0]).toContain('unregistered tool') - }) - - it('does NOT warn when the configured tool is already registered at load', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - ctx.tools.register(fastTool) - const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) - await ctx.plugin(timeoutPolicy, { tools: { fast: { timeoutMs: 30_000 } } }) - expect(warn).not.toHaveBeenCalled() - }) - - it('does NOT warn once a configured tool registers LATER (load-order safe)', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) - // Plugin loads before the tool it configures — the initial check would warn, - // so register first is the interesting case: mount with a not-yet-present - // name, then register it; the tools/change listener must clear it. - await ctx.plugin(timeoutPolicy, { tools: { late: { timeoutMs: 30_000 } } }) - expect(warn).toHaveBeenCalledTimes(1) // absent at load → warned once - warn.mockClear() - ctx.tools.register({ ...fastTool, name: 'late' }) // now it registers - // A subsequent tools/change must NOT re-warn the now-registered name. - ctx.tools.register({ ...fastTool, name: 'other' }) - expect(warn).not.toHaveBeenCalled() - }) - - it('warns at most once per unknown name across repeated tools/change', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined) - await ctx.plugin(timeoutPolicy, { tools: { ghost: { timeoutMs: 30_000 } } }) - expect(warn).toHaveBeenCalledTimes(1) // apply-time check - // Each register/unregister emits tools/change; the ghost stays unknown but - // must not be warned again. - const dispose = ctx.tools.register(fastTool) - dispose() - ctx.tools.register({ ...fastTool, name: 'another' }) - expect(warn).toHaveBeenCalledTimes(1) - }) -}) - describe('timeout-policy delegation (unconfigured / fast)', () => { - it('delegates an UNCONFIGURED tool unchanged and does not touch exec.signal', async () => { - const ctx = await setup({ other: { timeoutMs: 50 } }) + it('delegates a tool with NO declared budget unchanged and does not touch exec.signal', async () => { + const ctx = await setup() let seenSignal: AbortSignal | undefined - ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }) - + ctx.tools.register(defineTool({ name: 'probe', description: 'd', parameters: {}, + async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } })) const upstream = new AbortController().signal const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream }) expect(result.isError).toBe(false) - expect(seenSignal).toBe(upstream) // no deadline derived for an unconfigured tool + expect(seenSignal).toBe(upstream) }) - it('a configured tool that returns fast keeps its own result (no timeout)', async () => { - const ctx = await setup({ fast: { timeoutMs: 10_000 } }) - ctx.tools.register(fastTool) + it('a tool with a budget that returns fast keeps its own result (no timeout)', async () => { + const ctx = await setup() + ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000, + async execute() { return [{ type: 'text' as const, text: 'ok' }] } })) const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} }) expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }) }) - it('a configured tool receives the DERIVED deadline signal (not the caller signal) during dispatch', async () => { - const ctx = await setup({ probe: { timeoutMs: 10_000 } }) + it('a budgeted tool receives the DERIVED deadline signal (not the caller signal) during dispatch', async () => { + const ctx = await setup() let seenSignal: AbortSignal | undefined - ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }) - + ctx.tools.register(defineTool({ name: 'probe', description: 'd', parameters: {}, timeoutMs: 10_000, + async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } })) const upstream = new AbortController().signal await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream }) expect(seenSignal).toBeDefined() - expect(seenSignal).not.toBe(upstream) // the plugin swapped in its fused deadline signal + expect(seenSignal).not.toBe(upstream) }) }) describe('timeout-policy signal restoration', () => { it('restores the caller signal for post-execute after wrapping', async () => { - const ctx = await setup({ fast: { timeoutMs: 10_000 } }) - ctx.tools.register(fastTool) + const ctx = await setup() + ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000, + async execute() { return [{ type: 'text' as const, text: 'ok' }] } })) let postSignal: AbortSignal | undefined | 'unset' = 'unset' - ctx.on('tools/post-execute', async (exec, _result, next): Promise => { - postSignal = exec.signal - return next() - }) - + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { postSignal = exec.signal; return next() }) const upstream = new AbortController().signal await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {}, signal: upstream }) - expect(postSignal).toBe(upstream) // restored to the caller's own signal, not the deadline + expect(postSignal).toBe(upstream) }) it('deletes exec.signal again when the caller passed none', async () => { - const ctx = await setup({ fast: { timeoutMs: 10_000 } }) - ctx.tools.register(fastTool) + const ctx = await setup() + ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 10_000, + async execute() { return [{ type: 'text' as const, text: 'ok' }] } })) let hadSignal: boolean | undefined - ctx.on('tools/post-execute', async (exec, _result, next): Promise => { - hadSignal = 'signal' in exec && exec.signal !== undefined - return next() - }) - + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { hadSignal = 'signal' in exec && exec.signal !== undefined; return next() }) await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} }) - expect(hadSignal).toBe(false) // no caller signal → exec.signal absent again after wrapping + expect(hadSignal).toBe(false) }) }) @@ -205,13 +103,11 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => { afterEach(() => { vi.useRealTimers() }) it('replaces a cooperative tool result with TOOL_TIMEOUT when its own deadline fires', async () => { - const ctx = await setup({ slow: { timeoutMs: 100 } }) + const ctx = await setup() ctx.tools.register(cooperativeTool) - const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'slow', arguments: {} }) - await vi.advanceTimersByTimeAsync(150) // past the 100ms deadline: the timer fires, the tool settles + await vi.advanceTimersByTimeAsync(150) const result = await pending - expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'Error: tool call timed out after 100ms' }], @@ -220,33 +116,25 @@ describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => { }) }) - it('replaces a provider-owned abort ERROR result with TOOL_TIMEOUT (not WEB_ABORTED) when the signal was ours', async () => { - const ctx = await setup({ aborter: { timeoutMs: 100 } }) + it('replaces a provider-owned abort ERROR result with TOOL_TIMEOUT when the signal was ours', async () => { + const ctx = await setup() ctx.tools.register(abortThrowingTool) - const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'aborter', arguments: {} }) await vi.advanceTimersByTimeAsync(150) const result = await pending - - // Dispatch first normalized the thrown WEB_ABORTED into an isError result; - // the plugin then replaced THAT with TOOL_TIMEOUT because its own timer won. expect(result.isError).toBe(true) expect(result.error).toEqual({ name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }) expect(result.content[0]).toMatchObject({ text: 'Error: tool call timed out after 100ms' }) }) it('does NOT replace when the caller aborts first (upstream cancel, not our timeout)', async () => { - const ctx = await setup({ slow: { timeoutMs: 100 } }) + const ctx = await setup() ctx.tools.register(cooperativeTool) - const upstream = new AbortController() const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'slow', arguments: {}, signal: upstream.signal }) - upstream.abort('user cancelled') // fires before the 100ms timer + upstream.abort('user cancelled') await vi.advanceTimersByTimeAsync(0) const result = await pending - - // Our timer never fired, so timeoutOf(code) is undefined: the tool's own - // cooperative result stands, not a TOOL_TIMEOUT. expect(result.isError).toBe(false) expect(result.content[0]).toMatchObject({ text: 'stopped cooperatively' }) }) @@ -273,46 +161,38 @@ describe('timeout-policy disposal (HMR safety)', () => { await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRegistry) let seenSignal: AbortSignal | undefined - ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } }) - - // Mount the policy on its OWN fiber so disposing it removes only the wrapper. - const fiber = await ctx.plugin(timeoutPolicy, { tools: { probe: { timeoutMs: 10_000 } } }) + ctx.tools.register(defineTool({ name: 'probe', description: 'd', parameters: {}, timeoutMs: 10_000, + async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } })) + const fiber = await ctx.plugin(timeoutPolicy) const upstream = new AbortController().signal await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream }) - expect(seenSignal).not.toBe(upstream) // wrapper live: dispatch saw the derived deadline signal - + expect(seenSignal).not.toBe(upstream) await fiber.dispose() - // Listener gone: the tool now receives the caller's own signal unwrapped. A - // leaked stale wrapper would still derive a deadline and fail this. await ctx.tools.execute({ callId: CallId('c2'), name: 'probe', arguments: {}, signal: upstream }) expect(seenSignal).toBe(upstream) }) }) describe('dsh-timeout-policy real-load-path guard', () => { - it('has no default export and keeps name/inject/Config through unwrapExports', () => { + it('has no default export and keeps name/inject through unwrapExports', () => { expect('default' in timeoutPolicy).toBe(false) - const loader = Object.create(Loader.prototype) as Loader const unwrapped = loader.unwrapExports(timeoutPolicy) as Record expect(unwrapped).toBe(timeoutPolicy) expect(unwrapped.name).toBe('timeout-policy') expect(unwrapped.inject).toEqual(['tools']) expect(typeof unwrapped.apply).toBe('function') - expect(unwrapped.Config).toBeDefined() }) - it('boots over ctx.tools through the unwrapped module and wraps a configured tool', async () => { + it('boots over ctx.tools through the unwrapped module and wraps a budgeted tool', async () => { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRegistry) - ctx.tools.register(fastTool) - + ctx.tools.register(defineTool({ name: 'fast', description: 'd', parameters: {}, timeoutMs: 5_000, + async execute() { return [{ type: 'text' as const, text: 'ok' }] } })) const loader = Object.create(Loader.prototype) as Loader const unwrapped = loader.unwrapExports(timeoutPolicy) as Parameters[0] - const fiber = await ctx.plugin(unwrapped, { tools: { fast: { timeoutMs: 5_000 } } }) - // A configured fast tool still succeeds (deadline never fires); this proves - // the wrapper is live through the real Loader path. + const fiber = await ctx.plugin(unwrapped) const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} } satisfies ToolExecution) expect(result.isError).toBe(false) await fiber.dispose() From e491759f308e88d3c82bbd67e5fa96a10bf35688 Mon Sep 17 00:00:00 2001 From: kingwl Date: Wed, 8 Jul 2026 14:40:08 +0800 Subject: [PATCH 051/119] fix review finding: cap the detailed reminder's argument payload --- docs/config-catalog.md | 8 +++++ .../feature/2026-07-08-repeat-tool-guard.md | 9 +++--- packages/guard/repeat-tool-guard/README.md | 9 +++--- packages/guard/repeat-tool-guard/src/index.ts | 29 +++++++++++++++++-- .../tests/repeat-tool-guard.spec.ts | 29 +++++++++++++++++++ 5 files changed, 74 insertions(+), 10 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 18a1387baa..275c35ff85 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -372,6 +372,14 @@ export interface Config { include?: string[] /** Tool-name patterns transparent to the chain (neither count nor reset). */ exclude?: string[] + /** + * Maximum characters of canonical arguments quoted in the DETAILED reminder + * (default 500). Large payloads (a `write` body, a long command) would + * otherwise ride into the next request unbounded — precisely in a loop + * scenario; the cap bounds the reminder, never the detection (the chain key + * always compares the FULL canonical string). + */ + argumentsPreviewChars?: number } ``` diff --git a/docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md b/docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md index e0e9c28b5c..9d0446dcad 100644 --- a/docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md +++ b/docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md @@ -29,7 +29,7 @@ Two deliberate rules, both documented in [the package README](../../../../packag ### Reminder delivery -Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}` — the label is load-bearing per `HookContext`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit, and the loop appends buffered context as `context/message`(s) after the step's results, which the session renders as the tagged synthetic-user envelope and derived history replays. Thresholds escalate: the first configured threshold gets a short "you are repeating yourself, analyze the previous result" nudge; each later threshold gets the detailed form naming the tool, the repeat count, and the canonical arguments, and stating that the calls made no progress. The pi original hardcodes the gentle text to the literal count 3; the guard keys it to `thresholds[0]`, fixing that bug in the port. When the downstream decision already carries `additionalContext` (a hook bridge on the same call), the guard concatenates content under its own `source` — a `HookContext` holds one `MessageSource`, and `source.kind` is what framing depends on. +Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}` — the label is load-bearing per `HookContext`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit, and the loop appends buffered context as `context/message`(s) after the step's results, which the session renders as the tagged synthetic-user envelope and derived history replays. Thresholds escalate: the first configured threshold gets a short "you are repeating yourself, analyze the previous result" nudge; each later threshold gets the detailed form naming the tool, the repeat count, and the canonical arguments (head-truncated at `argumentsPreviewChars`, default 500 — a looping `write`-sized payload must not ride into the next request unbounded; the chain key always compares the full canonical string), and stating that the calls made no progress. The pi original hardcodes the gentle text to the literal count 3; the guard keys it to `thresholds[0]`, fixing that bug in the port. When the downstream decision already carries `additionalContext` (a hook bridge on the same call), the guard concatenates content under its own `source` — a `HookContext` holds one `MessageSource`, and `source.kind` is what framing depends on. ### Config @@ -37,9 +37,10 @@ Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-too - id: repeat-tool-guard name: '@deepseek-ai/dsh-repeat-tool-guard' config: - thresholds: [3, 5, 8] # default; consecutive counts that trigger a reminder - include: [] # tool-name patterns to track; empty ⇒ all tools - exclude: [todo_write] # tool-name patterns transparent to the chain + thresholds: [3, 5, 8] # default; consecutive counts that trigger a reminder + include: [] # tool-name patterns to track; empty ⇒ all tools + exclude: [todo_write] # tool-name patterns transparent to the chain + argumentsPreviewChars: 500 # default; cap on arguments quoted in the detailed reminder ``` `thresholds` is validated at load and throws on an empty list, a non-integer, a value below 2, or a duplicate — misconfiguration fails loud, replacing the pi original's silent fall-back to defaults. `include`/`exclude` entries support `*` wildcards. Patterns are predicates over whatever tools exist at call time, not references to a registry entry, so an entry matching no currently registered tool is NOT an error — unlike `toolOrder`'s referent check, `exclude: [mcp_*]` must stay valid in a deployment that loads no MCP tools. diff --git a/packages/guard/repeat-tool-guard/README.md b/packages/guard/repeat-tool-guard/README.md index 647426e382..dc385bc033 100644 --- a/packages/guard/repeat-tool-guard/README.md +++ b/packages/guard/repeat-tool-guard/README.md @@ -8,12 +8,13 @@ An advisory loop-breaker, not a model-facing tool: it never appears in the tool - id: repeat-tool-guard name: '@deepseek-ai/dsh-repeat-tool-guard' config: - thresholds: [3, 5, 8] # default; consecutive counts that trigger a reminder - include: [] # tool-name patterns to track; empty ⇒ all tools - exclude: [todo_write] # tool-name patterns transparent to the chain + thresholds: [3, 5, 8] # default; consecutive counts that trigger a reminder + include: [] # tool-name patterns to track; empty ⇒ all tools + exclude: [todo_write] # tool-name patterns transparent to the chain + argumentsPreviewChars: 500 # default; cap on arguments quoted in the detailed reminder ``` -`thresholds` fails loud at plugin load: an empty list, a non-integer, a value below 2, or a duplicate throws, never a silent fall-back to defaults. The list is normalized to ascending order; the FIRST threshold delivers a short generic nudge, every later threshold delivers the detailed form naming the tool, the run length, and the canonical arguments. +`thresholds` fails loud at plugin load: an empty list, a non-integer, a value below 2, or a duplicate throws, never a silent fall-back to defaults; `argumentsPreviewChars` equally rejects anything but an integer >= 1. The list is normalized to ascending order; the FIRST threshold delivers a short generic nudge, every later threshold delivers the detailed form naming the tool, the run length, and the canonical arguments — head-truncated at `argumentsPreviewChars` with an omitted-count marker, so a looping `write`/`edit` payload cannot ride into the next request unbounded (the chain key always compares the FULL canonical string; the cap bounds the reminder, never the detection). `include`/`exclude` entries support `*` wildcards and are predicates over whatever tools exist at call time, not references to registry entries — a pattern matching no currently registered tool is NOT an error (`exclude: [mcp_*]` stays valid in a deployment that loads no MCP tools), unlike `toolOrder`'s referent check. diff --git a/packages/guard/repeat-tool-guard/src/index.ts b/packages/guard/repeat-tool-guard/src/index.ts index e32d9efd67..919d0541ba 100644 --- a/packages/guard/repeat-tool-guard/src/index.ts +++ b/packages/guard/repeat-tool-guard/src/index.ts @@ -59,12 +59,21 @@ export interface Config { include?: string[] /** Tool-name patterns transparent to the chain (neither count nor reset). */ exclude?: string[] + /** + * Maximum characters of canonical arguments quoted in the DETAILED reminder + * (default 500). Large payloads (a `write` body, a long command) would + * otherwise ride into the next request unbounded — precisely in a loop + * scenario; the cap bounds the reminder, never the detection (the chain key + * always compares the FULL canonical string). + */ + argumentsPreviewChars?: number } export const Config: z = z.object({ thresholds: z.array(z.number()).default([3, 5, 8]), include: z.array(z.string()).default([]), exclude: z.array(z.string()).default([]), + argumentsPreviewChars: z.number().default(500), }) /** @@ -128,6 +137,16 @@ function wildcardToRegExp(pattern: string): RegExp { return new RegExp(`^${escaped.replaceAll('*', '.*')}$`) } +/** + * Head-truncate the canonical arguments for quoting in the detailed reminder, + * marking how much was omitted. Bounds only the model-visible text — the + * chain key always uses the full canonical string. + */ +function previewArguments(canonical: string, cap: number): string { + if (canonical.length <= cap) return canonical + return `${canonical.slice(0, cap)}… (+${canonical.length - cap} more chars)` +} + /** * Validate `thresholds` per the fail-loud contract and return them sorted * ascending (the escalation rule reads `thresholds[0]` as the gentle tier, so @@ -173,11 +192,15 @@ interface Chain { * @param config - validated {@link Config}; `thresholds` is re-checked fail-loud here. */ export function apply(ctx: Context, config: Config): void { - // schemastery's .default() guarantees the arrays are set after validation. + // schemastery's .default() guarantees the fields are set after validation. const thresholds = validateThresholds(config.thresholds as number[]) const thresholdSet = new Set(thresholds) const includePatterns = (config.include as string[]).map(wildcardToRegExp) const excludePatterns = (config.exclude as string[]).map(wildcardToRegExp) + const argumentsPreviewChars = config.argumentsPreviewChars as number + if (!Number.isInteger(argumentsPreviewChars) || argumentsPreviewChars < 1) { + throw new Error(`repeat-tool-guard: invalid argumentsPreviewChars ${argumentsPreviewChars} — must be an integer >= 1`) + } const chains = new Map() @@ -206,7 +229,9 @@ export function apply(ctx: Context, config: Config): void { const count = chain !== undefined && chain.key === key ? chain.count + 1 : 1 chains.set(exec.agent.id, { key, count }) if (!thresholdSet.has(count)) return undefined - const text = count === thresholds[0] ? GENTLE_REMINDER : detailedReminder(exec.name, count, canonical) + const text = count === thresholds[0] + ? GENTLE_REMINDER + : detailedReminder(exec.name, count, previewArguments(canonical, argumentsPreviewChars)) return { content: [{ type: 'text', text }], source: PLUGIN_SOURCE } } diff --git a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts index df59eb1019..565f1076b5 100644 --- a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts +++ b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts @@ -90,6 +90,28 @@ describe('threshold escalation', () => { }) describe('chain semantics', () => { + it('caps the detailed reminder arguments at argumentsPreviewChars (detection still keys on the full string)', async () => { + const ctx = await harness({ thresholds: [2, 3], argumentsPreviewChars: 24 }) + const bigPayload = 'x'.repeat(400) + const adapter = new MockAdapter([ + toolCallResponse('c1', 'probe', { body: bigPayload }), + toolCallResponse('c2', 'probe', { body: bigPayload }), + toolCallResponse('c3', 'probe', { body: bigPayload }), + textResponse('done'), + ]) + ctx.llm.registerAdapter(['mock'], adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + agent.send([{ type: 'text', text: 'go' }]) + await waitForIdle(ctx, agent) + + const found = reminders(agent) + expect(found).toHaveLength(2) // gentle at 2, detailed at 3 — full-key matching survived the cap + const detailed = found[1]!.text + expect(detailed).toContain('- arguments: {"body":"xxxxxxxxxxxxxx') // 24-char head + expect(detailed).toContain('… (+387 more chars)') + expect(detailed).not.toContain(bigPayload) + }) + it('a different tracked call resets the chain', async () => { const ctx = await harness() const adapter = new MockAdapter([ @@ -369,4 +391,11 @@ describe('config validation fails loud', () => { const ctx = await spine() await expect(ctx.plugin(RepeatToolGuard, { thresholds: [3, 3] })).rejects.toThrow(/duplicates/) }) + + it('rejects a non-positive or fractional argumentsPreviewChars', async () => { + const ctx = await spine() + await expect(ctx.plugin(RepeatToolGuard, { argumentsPreviewChars: 0 })).rejects.toThrow(/argumentsPreviewChars/) + const ctx2 = await spine() + await expect(ctx2.plugin(RepeatToolGuard, { argumentsPreviewChars: 12.5 })).rejects.toThrow(/argumentsPreviewChars/) + }) }) From 7a822ee4025a1084366fde49c23f93dc50d2166f Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 14:40:14 +0800 Subject: [PATCH 052/119] feat(tool-web): declare web tool timeout budgets via config fetchTimeoutMs/searchTimeoutMs (default 30000) resolve to each tool's ToolDefinition.timeoutMs, moving the budget's declaration home onto the owning tool plugin and preserving per-tool deployment override without a mistypable central tool-name map. --- packages/web/tool-web/README.md | 6 +++- packages/web/tool-web/src/fetch.ts | 17 +++++++---- packages/web/tool-web/src/index.ts | 22 ++++++++++++--- packages/web/tool-web/src/search.ts | 5 +++- .../web/tool-web/tests/integration.spec.ts | 13 +++++---- packages/web/tool-web/tests/tool-web.spec.ts | 28 +++++++++++++++++++ 6 files changed, 74 insertions(+), 17 deletions(-) diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md index e99eda5564..ab1326a21e 100644 --- a/packages/web/tool-web/README.md +++ b/packages/web/tool-web/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-tool-web -The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and `presentCall`. All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — the tool-call budget is deployment policy owned by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam. +The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and `presentCall`. All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — each tool's cooperative tool-call budget is declared here via config (`fetchTimeoutMs`/`searchTimeoutMs`, attached as `ToolDefinition.timeoutMs`) and enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam. Each tool is registered independently; a product that wants only one disables the other via config (`{ search: false }` / `{ fetch: false }`). @@ -18,6 +18,10 @@ Each tool is registered independently; a product that wants only one disables th | `search` | `true` | Register `web_search`. | | `fetch` | `true` | Register `web_fetch`. | | `searchMaxResults` | `8` | Upper bound on sources returned by one `web_search` call (the seam truncates a longer provider list and flags it). | +| `fetchTimeoutMs` | `30000` | Cooperative tool-call timeout budget (ms) for `web_fetch`. | +| `searchTimeoutMs` | `30000` | Cooperative tool-call timeout budget (ms) for `web_search`. | + +`fetchTimeoutMs`/`searchTimeoutMs` declare each tool's cooperative timeout budget (attached as `ToolDefinition.timeoutMs`), enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md); the model-facing schema exposes no timeout argument. ```yaml - id: tool-web diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts index 4bf9b5e2ff..571ce00797 100644 --- a/packages/web/tool-web/src/fetch.ts +++ b/packages/web/tool-web/src/fetch.ts @@ -5,10 +5,11 @@ * while the fetch provider owns safe retrieval (transport, redirects, caps). * * The model-facing schema exposes NO timeout knob: the tool-call budget is - * deployment policy owned by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` - * wrapper), matching the reference-agent `WebFetch` shape. This tool just - * forwards the (possibly deadline-derived) `exec.signal` to `ctx.web`; the - * provider keeps its own timeout only as a resource backstop for direct callers. + * deployment policy DECLARED via this package's `fetchTimeoutMs` config (attached + * as `ToolDefinition.timeoutMs`) and ENFORCED by `@deepseek-ai/dsh-timeout-policy` + * (a `tools/execute` wrapper), matching the reference-agent `WebFetch` shape. This + * tool just forwards the (possibly deadline-derived) `exec.signal` to `ctx.web`; + * the provider keeps its own timeout only as a resource backstop for direct callers. */ import type { Context } from 'cordis' @@ -23,7 +24,8 @@ import { htmlToMarkdown } from './html.ts' /** * Validate value constraints the schema DSL can't express: a non-blank `url`. * Throws a plain `Error` otherwise. No timeout parameter — the tool-call budget - * is deployment policy (`@deepseek-ai/dsh-timeout-policy`), not a model argument. + * is deployment policy declared via `fetchTimeoutMs` config and enforced by + * `@deepseek-ai/dsh-timeout-policy`, not a model argument. * * @param args - the schema-validated `web_fetch` arguments. * @returns the arguments as the seam's request fields. @@ -80,8 +82,10 @@ export function presentFetchCall(args: { url: string }): GenericCallView { * * @param ctx - context whose `tools` and `systemPrompt` registries receive the * registrations; both are effect-scoped and unregister on plugin dispose. + * @param timeoutMs - the cooperative tool-call budget (ms) attached as the tool's + * `ToolDefinition.timeoutMs` for `@deepseek-ai/dsh-timeout-policy` to enforce. */ -export function applyWebFetchTool(ctx: Context): void { +export function applyWebFetchTool(ctx: Context, timeoutMs: number): void { ctx.systemPrompt.section({ name: 'tool:web_fetch', order: 111, @@ -94,6 +98,7 @@ export function applyWebFetchTool(ctx: Context): void { parameters: { url: { type: 'string', required: true, description: 'The HTTP(S) URL to fetch.' }, }, + timeoutMs, async execute(args, exec): Promise { const input = parseFetchArgs(args) const result = await ctx.web.fetch( diff --git a/packages/web/tool-web/src/index.ts b/packages/web/tool-web/src/index.ts index 78b6a4bdf3..0f948eacb6 100644 --- a/packages/web/tool-web/src/index.ts +++ b/packages/web/tool-web/src/index.ts @@ -33,7 +33,10 @@ export const name = 'tool-web' /** Services required by the web tool suite. */ export const inject = ['tools', 'web', 'systemPrompt'] -/** Plugin config: which web tools to register, and the `web_search` source cap. */ +/** Default cooperative tool-call timeout budget (ms) for the web tools. */ +export const DEFAULT_WEB_TOOL_TIMEOUT_MS = 30_000 + +/** Plugin config: which web tools to register, the source cap, and per-tool budgets. */ export interface Config { /** Register `web_search`. Defaults to true. */ search?: boolean @@ -41,12 +44,18 @@ export interface Config { fetch?: boolean /** Upper bound on sources returned by one `web_search` call. */ searchMaxResults?: number + /** Cooperative timeout budget (ms) for `web_fetch`. Defaults to 30000. */ + fetchTimeoutMs?: number + /** Cooperative timeout budget (ms) for `web_search`. Defaults to 30000. */ + searchTimeoutMs?: number } export const Config: z = z.object({ search: z.boolean().default(true), fetch: z.boolean().default(true), searchMaxResults: z.number().default(WEB_SEARCH_MAX_RESULTS), + fetchTimeoutMs: z.number().default(DEFAULT_WEB_TOOL_TIMEOUT_MS), + searchTimeoutMs: z.number().default(DEFAULT_WEB_TOOL_TIMEOUT_MS), }) /** The shape after schemastery applies its defaults to every field. */ @@ -61,7 +70,10 @@ function assertPositiveInteger(name: string, value: number): void { /** * Register the enabled web tools. `search`/`fetch` default to true; a product - * that wants only one disables the other in config. The tools' disposers are + * that wants only one disables the other in config. Each tool's cooperative + * timeout budget (`fetchTimeoutMs`/`searchTimeoutMs`, default 30000) is resolved + * here and attached to the tool as `ToolDefinition.timeoutMs` for + * `@deepseek-ai/dsh-timeout-policy` to enforce. The tools' disposers are * fiber-scoped (the effect-based registries clean up on dispose), so no manual * teardown is needed. */ @@ -69,6 +81,8 @@ export function apply(ctx: Context, config: Config): void { // schemastery (Config) has already filled every defaulted field. const resolved = config as ResolvedConfig assertPositiveInteger('searchMaxResults', resolved.searchMaxResults) - if (resolved.search) applyWebSearchTool(ctx, resolved.searchMaxResults) - if (resolved.fetch) applyWebFetchTool(ctx) + assertPositiveInteger('fetchTimeoutMs', resolved.fetchTimeoutMs) + assertPositiveInteger('searchTimeoutMs', resolved.searchTimeoutMs) + if (resolved.search) applyWebSearchTool(ctx, resolved.searchMaxResults, resolved.searchTimeoutMs) + if (resolved.fetch) applyWebFetchTool(ctx, resolved.fetchTimeoutMs) } diff --git a/packages/web/tool-web/src/search.ts b/packages/web/tool-web/src/search.ts index 3776940cde..a7587d328b 100644 --- a/packages/web/tool-web/src/search.ts +++ b/packages/web/tool-web/src/search.ts @@ -92,8 +92,10 @@ export function presentSearchCall(args: { query: string }): GenericCallView { * registrations; both are effect-scoped and unregister on plugin dispose. * @param maxResults - the deployment's source cap, sent as every seam * request's `maxResults`. + * @param timeoutMs - the cooperative tool-call budget (ms) attached as the tool's + * `ToolDefinition.timeoutMs` for `@deepseek-ai/dsh-timeout-policy` to enforce. */ -export function applyWebSearchTool(ctx: Context, maxResults: number): void { +export function applyWebSearchTool(ctx: Context, maxResults: number, timeoutMs: number): void { ctx.systemPrompt.section({ name: 'tool:web_search', order: 110, @@ -106,6 +108,7 @@ export function applyWebSearchTool(ctx: Context, maxResults: number): void { parameters: { query: { type: 'string', required: true, description: 'The search query.' }, }, + timeoutMs, async execute(args, exec): Promise { const input = parseSearchArgs(args) const result = await ctx.web.search( diff --git a/packages/web/tool-web/tests/integration.spec.ts b/packages/web/tool-web/tests/integration.spec.ts index 03ad76ca0f..de804e2bcd 100644 --- a/packages/web/tool-web/tests/integration.spec.ts +++ b/packages/web/tool-web/tests/integration.spec.ts @@ -41,9 +41,11 @@ beforeEach(async () => { await ctx.plugin(WebService, { searchProvider: WebSearchExa.EXA_PROVIDER_ID, fetchProvider: WebFetchLocal.LOCAL_FETCH_PROVIDER_ID }) await ctx.plugin(WebFetchLocal, {}) await ctx.plugin(WebSearchExa, { apiKey: 'exa-key', baseURL: 'https://api.exa.test' }) - // The shipped deployment shape: the tool-call budget is deployment policy over - // the model tools, set above the provider backstop so the policy normally wins. - await ctx.plugin(TimeoutPolicy, { tools: { web_fetch: { timeoutMs: 30_000 }, web_search: { timeoutMs: 30_000 } } }) + // The shipped deployment shape: the tool-call budget is declared by tool-web + // config (default 30s, attached as ToolDefinition.timeoutMs) and enforced by + // the zero-config timeout-policy plugin, set above the provider backstop so the + // policy normally wins. + await ctx.plugin(TimeoutPolicy) fiber = await ctx.plugin(ToolWeb) }) @@ -135,8 +137,9 @@ describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetc await tctx.plugin(WebService, { fetchProvider: WebFetchLocal.LOCAL_FETCH_PROVIDER_ID }) // Provider backstop well ABOVE the tool-call budget, so the policy wins. await tctx.plugin(WebFetchLocal, { timeoutMs: 30_000, maxTimeoutMs: 60_000 }) - await tctx.plugin(TimeoutPolicy, { tools: { web_fetch: { timeoutMs: 50 } } }) - tfiber = await tctx.plugin(ToolWeb) + await tctx.plugin(TimeoutPolicy) + // The tool-call budget is declared by tool-web config, enforced by the policy. + tfiber = await tctx.plugin(ToolWeb, { fetchTimeoutMs: 50 }) }) afterEach(async () => { diff --git a/packages/web/tool-web/tests/tool-web.spec.ts b/packages/web/tool-web/tests/tool-web.spec.ts index e060f90a4c..4bb2728df7 100644 --- a/packages/web/tool-web/tests/tool-web.spec.ts +++ b/packages/web/tool-web/tests/tool-web.spec.ts @@ -349,3 +349,31 @@ describe('searchMaxResults is plugin config', () => { .rejects.toThrow(/tool-web: searchMaxResults must be a positive integer/) }) }) + +describe('tool-call timeout budget is plugin config', () => { + it('attaches the default 30s budget to web_fetch and web_search', async () => { + const { fiber, ctx } = await mountTools() + expect(ctx.tools.get('web_fetch')?.timeoutMs).toBe(30_000) + expect(ctx.tools.get('web_search')?.timeoutMs).toBe(30_000) + await fiber.dispose() + }) + + it('honors per-tool timeout overrides from config', async () => { + const { fiber, ctx } = await mountTools({ config: { fetchTimeoutMs: 60_000, searchTimeoutMs: 10_000 } }) + expect(ctx.tools.get('web_fetch')?.timeoutMs).toBe(60_000) + expect(ctx.tools.get('web_search')?.timeoutMs).toBe(10_000) + await fiber.dispose() + }) + + it.each([ + ['fetchTimeoutMs', { fetchTimeoutMs: 0 }], + ['searchTimeoutMs', { searchTimeoutMs: -5 }], + ])('rejects a non-positive-integer %s at load', async (key, config) => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(WebService, {}) + await expect(ctx.plugin(ToolWeb, config)) + .rejects.toThrow(new RegExp(`tool-web: ${key} must be a positive integer`)) + }) +}) From 395a0b8336965cb0f1ea9744830cbb4e1624df54 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 15:06:02 +0800 Subject: [PATCH 053/119] docs(timeout): update RFC + generated catalogs for the declaration split MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The RFC's deployment-policy decision is unchanged; state the current mechanism in place — the per-tool budget is declared on ToolDefinition (timeoutMs, set by the owning tool plugin from its config) and the enforcer is zero-config, so a mistyped tool name is impossible. Regenerate config-catalog (timeout-policy -> no-config; tool-web gains fetch/searchTimeoutMs), the event graph (tools/change loses its timeout-policy consumer), the ToolDefinition type-equiv block, and a source-line drift in the cordis services catalog. --- docs/config-catalog.md | 34 ++++--------------- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/tools.md | 8 +++++ docs/event-producer-consumer.md | 2 +- .../2026-07-07-tool-call-timeout-policy.md | 27 +++++++-------- 5 files changed, 30 insertions(+), 43 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 20254f3e35..1680bb40ec 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -602,31 +602,6 @@ export interface Config { Source: [`packages/core/system-prompt/src/index.ts:179`](../packages/core/system-prompt/src/index.ts) -## `@deepseek-ai/dsh-timeout-policy` - -Requires: `tools` - -```ts config-catalog -/** - * Plugin config: per-tool timeout policy, keyed by the model-facing tool name. - * There is deliberately NO global default (a global budget would silently start - * failing any tool that happens to run long once the plugin loads) and NO model - * override (timeout is deployment policy, not prompt semantics) in this version. - */ -export interface Config { - /** Timeout policy per tool name; an unlisted tool gets no deadline from this plugin. */ - tools?: Record -} - -/** Per-tool timeout policy. `timeoutMs` is required and must be positive finite. */ -export interface ToolTimeoutPolicy { - /** The per-call cooperative deadline for this tool, in milliseconds. */ - timeoutMs: number -} -``` - -Source: [`packages/timeout/timeout-policy/src/index.ts:64`](../packages/timeout/timeout-policy/src/index.ts) - ## `@deepseek-ai/dsh-tool-fs` Requires: `tools` · `fs` · `systemPrompt` @@ -683,7 +658,7 @@ Source: [`packages/subagent/tool-subagent/src/index.ts:44`](../packages/subagent Requires: `tools` · `web` · `systemPrompt` ```ts config-catalog -/** Plugin config: which web tools to register, and the `web_search` source cap. */ +/** Plugin config: which web tools to register, the source cap, and per-tool budgets. */ export interface Config { /** Register `web_search`. Defaults to true. */ search?: boolean @@ -691,10 +666,14 @@ export interface Config { fetch?: boolean /** Upper bound on sources returned by one `web_search` call. */ searchMaxResults?: number + /** Cooperative timeout budget (ms) for `web_fetch`. Defaults to 30000. */ + fetchTimeoutMs?: number + /** Cooperative timeout budget (ms) for `web_search`. Defaults to 30000. */ + searchTimeoutMs?: number } ``` -Source: [`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts) +Source: [`packages/web/tool-web/src/index.ts:40`](../packages/web/tool-web/src/index.ts) ## `@deepseek-ai/dsh-web` @@ -818,6 +797,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts)) - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts)) - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)) +- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts)) - `@deepseek-ai/dsh-tool-bash` — requires `tools` · `bash` · `systemPrompt` ([`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)) - `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts)) - `@deepseek-ai/dsh-tools` — requires `systemPrompt` ([`packages/core/tools/src/index.ts`](../packages/core/tools/src/index.ts)) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index de47287a83..517d7196a9 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -205,7 +205,7 @@ async execute(exec: ToolExecution): Promise Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:299`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:307`](../../packages/core/tools/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md index a38a5b9c15..96d3e79bdc 100644 --- a/docs/core-data-structures/tools.md +++ b/docs/core-data-structures/tools.md @@ -11,6 +11,14 @@ A `ToolSchema` (the model-facing fields) plus the `execute` function and optiona ```ts type-equiv interface ToolDefinition extends ToolSchema { execute(args: unknown, exec: ToolExecution): Promise + /** + * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline. + * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it + * is NEVER sent to the model — `schemas()` whitelists only name/description/ + * parameters. Declaring it asserts this tool forwards `exec.signal` to a + * cooperative implementation that can reach quiescence when the signal aborts. + */ + timeoutMs?: number /** * 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 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index ce8e17e851..0c95164728 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -31,7 +31,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:118`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | [`timeout-policy`](../packages/timeout/timeout-policy) | +| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:118`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:113`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:77`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | diff --git a/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md index edde6aca43..362f5cb5e8 100644 --- a/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md +++ b/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md @@ -14,7 +14,7 @@ Tool-call timeout is a policy that applies only to model-facing tool execution, - `@deepseek-ai/dsh-timeout` remains the shared library that owns `deadline()` and `timeoutOf()`. - `@deepseek-ai/dsh-tools` has an around-dispatch waterfall, `tools/execute`, between `tools/pre-execute` and `tools/post-execute`. -- `@deepseek-ai/dsh-timeout-policy` reads deployment config and wraps configured tool calls by deriving a new `exec.signal`. +- `@deepseek-ai/dsh-timeout-policy` reads each tool's declared `timeoutMs` from the registry and wraps a call that has one by deriving a new `exec.signal`. The execution pipeline is: @@ -28,7 +28,7 @@ ctx.tools.execute(exec) -> tools/post-execute ``` -The default behavior is conservative: an unconfigured tool receives no `TOOL_TIMEOUT` deadline from the plugin. +The default behavior is conservative: a tool that declares no `timeoutMs` receives no `TOOL_TIMEOUT` deadline from the plugin. ### The `tools/execute` around seam @@ -38,20 +38,19 @@ That the catch is the base `next` — not something outside the waterfall — is ### The `timeout-policy` plugin -The plugin is `@deepseek-ai/dsh-timeout-policy`, a function/namespace plugin (`name` / `Config` / `apply`) in the `packages/timeout/` group. Its config is per tool, with no global default and no model override: +The plugin is `@deepseek-ai/dsh-timeout-policy`, a zero-config function/namespace plugin (`name` / `inject` / `apply`) in the `packages/timeout/` group. The per-tool budget is DECLARED on the tool, not on this plugin: a `ToolDefinition` carries an optional `timeoutMs`, which the owning tool plugin sets from its own config. `dsh-tool-web`, for example, resolves `fetchTimeoutMs` / `searchTimeoutMs` (default 30000) onto the `web_fetch` / `web_search` definitions: ```yaml - id: timeout-policy name: '@deepseek-ai/dsh-timeout-policy' +- id: tool-web + name: '@deepseek-ai/dsh-tool-web' config: - tools: - web_fetch: - timeoutMs: 30000 - web_search: - timeoutMs: 30000 + fetchTimeoutMs: 30000 + searchTimeoutMs: 30000 ``` -`timeoutMs` is required for every configured tool and must be positive finite (validated at `apply`). For a configured tool the listener arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')`, swaps the derived signal onto `exec` for the downstream dispatch, restores the caller's own signal afterward, and returns a structured `TOOL_TIMEOUT` result when `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches. An unconfigured tool delegates unchanged. +Keeping the tool name out of this plugin's config is deliberate: a budget keyed by a free-text tool name could be mistyped (`web_fech`) and then silently apply to nothing. Declaring `timeoutMs` on the tool makes that failure class structurally impossible — the enforcer reads `ctx.tools.get(exec.name)?.timeoutMs`, and `exec.name` is the tool being dispatched, so the lookup always resolves and there is no unknown-name path to warn or throw about. `timeoutMs` is validated positive-finite by `defineTool` at definition time. For a tool that declares a budget the listener arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')`, swaps the derived signal onto `exec` for the downstream dispatch, restores the caller's own signal afterward, and returns a structured `TOOL_TIMEOUT` result when `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches. A tool with no declared budget delegates unchanged. Signal replacement is by **in-place mutation of `exec.signal`**, not by passing a new object to `next()`. Cordis's waterfall `next()` ignores any arguments handed to it and re-invokes downstream listeners with the shared payload array (`vendor/cordis/src/events.ts`), so the documented cordis idiom — mutate the shared object, then delegate — is the only mechanism that reaches dispatch. The plugin restores `exec.signal` to the caller's original in a `finally` so `tools/post-execute` never sees this plugin's (possibly already-aborted) deadline signal. @@ -68,7 +67,7 @@ function toolTimeoutResult(callId: CallId, timeoutMs: number): ToolExecutionResu } ``` -This is a cooperative deadline. It does not kill arbitrary work by racing the tool promise; the tool or the capability it calls must honor `exec.signal` and reach quiescence. "Configured" therefore MEANS "cooperative with `exec.signal`", which the plugin README states as its contract. +This is a cooperative deadline. It does not kill arbitrary work by racing the tool promise; the tool or the capability it calls must honor `exec.signal` and reach quiescence. Declaring `timeoutMs` therefore MEANS "this tool is cooperative with `exec.signal`", which the plugin README states as its contract. No new session event is needed for reconstructability: `TOOL_TIMEOUT` is the final model-facing `tool/result` for that call, so the existing session log already records the content and structured `{ name, code }` error the next model request sees. @@ -82,7 +81,7 @@ No new session event is needed for reconstructability: `TOOL_TIMEOUT` is the fin `read`, `write`, `edit`, `todo_write`, `bash_output`, and `bash_kill` do not opt into tool-call timeout: they are local filesystem or short registry/session operations where a deadline would be best-effort only or unnecessary. -A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and a deployment configures `timeout-policy` for its budget. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is outside this cut. +A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and declares its own `timeoutMs` (from its plugin's config) for the enforcer to apply. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is outside this cut. ## Alternatives considered @@ -92,7 +91,7 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit **Move all timeout policy out of bash-local immediately.** Cleaner long-term — bash-local would become a pure subprocess executor and all callers would own their deadlines. It loses as the first step because hooks call `ctx.bash` directly and the bash model tool has foreground/background semantics that are not the same tool-call lifetime. Keeping `BASH_TIMEOUT` preserves those paths while tool-call timeout proves itself on simpler tools. -**Use a global default budget for every tool.** Convenient, but it surprises tool authors: any tool that accidentally runs longer than the global budget would start failing once the plugin loads. Per-tool config makes adoption deliberate. +**Use a global default budget for every tool.** Convenient, but it surprises tool authors: any tool that accidentally runs longer than the global budget would start failing once the plugin loads. A per-tool declared budget makes adoption deliberate. **Expose a model-facing `timeout_ms` override.** Claude Code's `WebFetch`/`WebSearch` and Codex's web tools keep timeout out of the model-call shape. A model override would make timeout part of prompt semantics and force schema/argument-stripping rules into `timeout-policy`. Web timeout stays deployment policy only. @@ -106,6 +105,6 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit - `@deepseek-ai/dsh-tools` gains an around-dispatch surface after the interception seams deliberately split pre/post tool hooks. Its contract is narrow — wrap registry dispatch, not replace the pre-gate or post-result policy — and the base `next()` is dispatch-with-normalization so a wrapper never sees a raw tool throw. - Multiple `tools/execute` listeners compose by ordinary Cordis waterfall order: a listener that calls `next()` wraps downstream listeners plus dispatch; one that returns without `next()` short-circuits them. A deployment combining timeout with a future retry/sandbox/metrics wrapper chooses semantics by registration order ("timeout covers the whole retry" vs "timeout covers each attempt"). -- Config-only opt-in is a deliberate misconfiguration risk: a deployment can configure a timeout for a tool that does not honor `exec.signal`, and that tool will not stop on timeout. The plugin contract states that "configured" means cooperative; the web tools prove the pattern on tools that already forward the signal. +- Opt-in by declaration is a deliberate misconfiguration risk: a tool can declare a `timeoutMs` without honoring `exec.signal`, and that tool will not stop on timeout. The plugin contract states that declaring a budget means cooperative; the web tools prove the pattern on tools that already forward the signal. - During the transition `bash` and the migrated web tools use different timeout paths on purpose: `TOOL_TIMEOUT` is the model-facing tool-call budget, while `BASH_TIMEOUT` remains the bash backend timeout used by bash and hooks. -- Deviation from the literal proposal, recorded per the implemented-RFC rule: the plugin package is `@deepseek-ai/dsh-timeout-policy` (not `tool-timeout`), and signal replacement is in-place `exec.signal` mutation before `next()` (not `next({ ...exec, signal })`, which cordis ignores). Both are described in `## Decision` above. +- Deviation from the literal proposal, recorded per the implemented-RFC rule: the plugin package is `@deepseek-ai/dsh-timeout-policy` (not `tool-timeout`), signal replacement is in-place `exec.signal` mutation before `next()` (not `next({ ...exec, signal })`, which cordis ignores), and the per-tool budget is declared on the `ToolDefinition` (`timeoutMs`, set by the owning tool plugin from its config) rather than mapped by tool name in this plugin's config — so the enforcer is zero-config and a mistyped tool name is impossible. All three are described in `## Decision` above. From a7c055270d4dff8c010380d7f5a505b7bc442e9f Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 15:10:15 +0800 Subject: [PATCH 054/119] chore(timeout-policy): drop now-unused schemastery dependency The zero-config enforcer no longer imports schemastery (its Config was removed); knip flags the stale dependency. Remove it from the manifest and sync the lockfile. --- packages/timeout/timeout-policy/package.json | 3 --- pnpm-lock.yaml | 4 ---- 2 files changed, 7 deletions(-) diff --git a/packages/timeout/timeout-policy/package.json b/packages/timeout/timeout-policy/package.json index 0cf3febc75..9069735b86 100644 --- a/packages/timeout/timeout-policy/package.json +++ b/packages/timeout/timeout-policy/package.json @@ -27,9 +27,6 @@ "@deepseek-ai/dsh-tools": "^0.0.1", "cordis": "^4.0.0-rc.6" }, - "dependencies": { - "schemastery": "^3.18.0" - }, "devDependencies": { "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-timeout": "workspace:^", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c966ce3d29..c057494cf0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -817,10 +817,6 @@ importers: version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) packages/timeout/timeout-policy: - dependencies: - schemastery: - specifier: ^3.18.0 - version: 3.18.0 devDependencies: '@deepseek-ai/dsh-llm': specifier: workspace:^ From ea4c10d7530ce85fec1de3ed5114c3f8581e2962 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 15:44:30 +0800 Subject: [PATCH 055/119] refactor(agent): replace the per-step advice seam with agent/session-prefix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review discussion converged on the industry shape (Claude Code caches user context per conversation; Codex separates initial context from diffs; Kimi appends at continuation boundaries to protect prompt caching): stable openers belong in a compose-once prefix, mid-session changes belong in append-only history — not in a per-request slot. agent/session-prefix fires ONCE per loop instance, lazily on its first request-building step: the composed Message[] is deep-frozen, cached on the transmission bookkeeping, recorded as EpochHeader.messagePrefix on the anchoring 'initial'/'resume' snapshot, and reused verbatim for every request the instance sends — prefix stability is structural, not a producer discipline, and a resume recomposes with attributable drift. The request is messagePrefix + boundary snapshot. The per-step RequestAdvice/RequestAdviceContext surface and the messageSuffix header field are dropped: the tail slot had no consumer, and every current update pattern (new AGENTS.md discovered, memory update, skills change) routes through the existing append-only history channels — inject(), tools/post-execute additionalContext, prompt-submit additionalContext — each paid once and prefix-cached thereafter. The messagePrefix delta arm stays for codec totality; the loop never produces one in practice. --- docs/architecture.md | 10 +- docs/cordis-catalog/events.md | 38 ++--- docs/core-data-structures/core.md | 40 +---- docs/core-data-structures/session.md | 21 ++- docs/event-producer-consumer.md | 24 +-- docs/persistence-catalog.md | 32 ++-- .../2026-07-05-reconstructable-requests.md | 8 +- packages/core/agent-loop/README.md | 8 +- packages/core/agent-loop/src/loop.ts | 66 +++++---- packages/core/agent-loop/src/request-log.ts | 11 +- .../agent-loop/tests/interception.spec.ts | 137 +++++++----------- packages/core/agent/README.md | 2 +- packages/core/agent/src/types.ts | 119 ++++----------- packages/core/session/README.md | 2 +- packages/core/session/src/request-header.ts | 28 ++-- packages/core/session/src/types.ts | 28 ++-- .../core/session/tests/request-header.spec.ts | 29 ++-- packages/llm/llm/src/types.ts | 4 +- packages/support/invariants/src/index.ts | 14 +- .../invariants/tests/invariants.spec.ts | 17 +-- scripts/type-equiv.manifest.json | 2 - 21 files changed, 260 insertions(+), 380 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 1ba6eb1ef9..0358c73d52 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -38,7 +38,7 @@ Events are the harness extension API. Each service owns the vocabulary for the b ### Event Domains -Use the event domain to decide where new behavior belongs: +Pick the event domain for new behavior: - **Session events** are durable, replayable facts. Turn and step boundaries, user input, assistant output, tool calls, tool results, steering, compaction records, and tool-owned durable facts append to the session log and flow through `session/event`. - **Agent events** are live runtime surfaces. They carry the live `Agent` handle for status, diagnostics, prompt admission, call-config shaping, result validation, and continuation policy. @@ -46,7 +46,7 @@ Use the event domain to decide where new behavior belongs: ### Interception Semantics -Waterfall events behave like around-middleware: a listener delegates by calling `next()` and vetoes or takes over by returning without it. Full rule: [Cordis waterfall semantics](cordis-primer.md#cordis-waterfall-semantics). +Waterfall events behave like around-middleware: a listener delegates by calling `next()`; returning without it vetoes or takes over. Full rule: [Cordis waterfall semantics](cordis-primer.md#cordis-waterfall-semantics). ## Default Loop Lifecycle @@ -72,7 +72,7 @@ forever: agent/pre-step 'step/start' snapshot the derived messages (the reconstruction boundary) - agent/request (config only) -> agent/request-advice -> log request/header -> llm/stream (frozen) + agent/request (config only) -> agent/session-prefix (first request) -> log request/header -> llm/stream (frozen) 'assistant/chunk' agent/step-result 'assistant/message' @@ -108,7 +108,7 @@ Every session event is turn-enclosed. Reloading a crashed session preserves the The session log is the source of truth. `deriveMessages()` projects session events into the `Message[]` sent to the model; raw `assistant/chunk` events stay in the log for replay and UI fidelity. Replay, fork, resume, transcript rendering, telemetry, and persistence all derive from the same event stream. -**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` framed by the header's request-only `messagePrefix`/`messageSuffix`, headers by folding `request/header` — and dev invariants assert this ([reconstructability RFC](rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). +**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` fronted by the header's session prefix, headers by folding `request/header` — and dev invariants assert this ([reconstructability RFC](rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). Durability is a plugin concern. Persistence backends buffer synchronous `session/event` notifications and the loop awaits a turn-end checkpoint before moving on. The `SessionPersistence` seam stores `SessionEvent` directly, with metadata in `SessionHeader`; JSONL and SQLite share one contract suite. @@ -141,7 +141,7 @@ New behavior should attach to a documented seam; changing the shipped loop requi | Add command execution | implement and register a `ctx.bash` backend | | Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events | | Intercept prompts, requests, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` waterfall | -| Add per-request context that must not become history | contribute request-only messages on `agent/request-advice`; logged on the request header | +| Add a session-stable request prefix outside history | compose it on `agent/session-prefix`, once per loop instance; logged on the request header | | Add UI or editor integration | drive `ctx.agents` and render from `session/event` | | Add durable session state | add a `SessionEventMap` member and render/replay from the log | | Fork a live session | use `ctx.sessions.fork(source, boundary?, childSessionId?)` | diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 7ee3c0e2f5..20cd367f32 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -23,7 +23,7 @@ An agent was registered in the AgentRegistry and is ready to receive messages. Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:313`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:265`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -35,7 +35,7 @@ An agent was disposed and removed from the registry; its fiber and any in-flight Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:320`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:272`](../../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:512`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:455`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -61,7 +61,7 @@ Serial (awaited in registration order), not a waterfall: a listener mutates the Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:398`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:350`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -73,7 +73,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a 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:411`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:363`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -85,11 +85,11 @@ A message entered the agent's inbox (queued or steering). `source` is the resolv 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:338`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:290`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall -Waterfall: shape the step's call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use). Config is ALL a listener shapes here: every request is a pure function of the session log (the reconstructability RFC), so model-visible content flows through the log channels — `inject()`, steering, prompt-submit `additionalContext`, prompt sections via `system-prompt/assemble`, or header-logged request-only messages via agent/request-advice — never through request mutation, and the loop records whatever config the request actually uses as a `request/header*` event before dispatch. The step's messages are already snapshotted when this fires (the `step/start` boundary): an `inject()` from a listener here lands in the log but joins the NEXT request. For surface mutation that must precede the snapshot (compaction), use agent/pre-step. Call `next()` to delegate, or return an LlmCallConfig without it to short-circuit. +Waterfall: shape the step's call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use). Config is ALL a listener shapes here: every request is a pure function of the session log (the reconstructability RFC), so model-visible content flows through the log channels — `inject()`, steering, prompt-submit `additionalContext`, prompt sections via `system-prompt/assemble`, or the header-logged session prefix via agent/session-prefix — never through request mutation, and the loop records whatever config the request actually uses as a `request/header*` event before dispatch. The step's messages are already snapshotted when this fires (the `step/start` boundary): an `inject()` from a listener here lands in the log but joins the NEXT request. For surface mutation that must precede the snapshot (compaction), use agent/pre-step. Call `next()` to delegate, or return an LlmCallConfig without it to short-circuit. ```ts cordis-catalog 'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise @@ -97,23 +97,23 @@ Waterfall: shape the step's call configuration — model switching, sampling ove Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:435`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:387`](../../packages/core/agent/src/types.ts) -### `agent/request-advice` — waterfall +### `agent/session-prefix` — waterfall -Waterfall: weave request-ONLY advice around the derived history — a RequestAdvice whose `before` messages sit in front of the ENTIRE boundary snapshot in `GenerateOptions.messages` and whose `after` messages follow its last message. Fires once per step, inside the open step, after the agent/request config waterfall and before the loop logs the request header. This is the seam for per-request advisory context the model must see NOW but that must NOT become durable history (a skills catalog, an environment reminder): contributions are recorded on the request's `request/header*` event (`EpochHeader.messagePrefix` / `messageSuffix`) — never as session messages — so `Session.deriveMessages()` stays untouched and the request remains reconstructable from the log. +Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider's system slot) on every request this loop instance sends. Fired ONCE per loop instance, lazily on its first request-building step; the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the instance's anchoring `'initial'`/`'resume'` header snapshot, and reused verbatim for every subsequent request — never recomputed mid-session, so the provider prefix cache holds by construction (a process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` snapshot). -The seed is frozen and empty; a contributing listener returns a NEW RequestAdvice extending `await next()` (spread its arrays — never mutate them), so contributions compose across plugins in registration order. The boundary snapshot is already taken when this fires: a `session.append`/`inject()` from a listener here lands in the log but joins the NEXT request — contribute through the returned value, not the session. Call `next()` to delegate, or return a RequestAdvice without it to short-circuit. +This is the home for session-stable openers the model must always see but that must NOT become durable history — a skills catalog, an AGENTS.md digest, a workspace baseline: `Session.deriveMessages()` never returns the prefix, and the header events are its only durable record, so the request stays reconstructable from the log. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, a `tools/post-execute` decision's `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter. -Pick the channel by change frequency (the cost model): a contribution rides the request's uncached tail, re-tokenized at full price on EVERY request it appears in — cheap only while small. Session-FROZEN content belongs in `before`, where it extends the cacheable prefix at zero marginal cost (but changing it mid-session invalidates the provider cache for the entire history after it). A LOW-FREQUENCY change notice belongs in durable history via `agent.inject()` — appended once, prefix-cached thereafter. Reserve `after` for small, frequently refreshed state snapshots, where a durable chain of stale copies would bloat the log and mislead the model. +The seed is a frozen empty list; a contributing listener returns a NEW array extending `await next()` (`[...prefix, mine]` — never an in-place push), so contributions compose across plugins in registration order and compose deterministically for a fixed plugin set. Call `next()` to delegate, or return a list without it to short-circuit. ```ts cordis-catalog -'agent/request-advice'(agent: Agent, turn: number, step: number, advice: RequestAdvice, context: RequestAdviceContext, next: () => Promise): Promise +'agent/session-prefix'(agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise): Promise ``` -Types: [Agent](../core-data-structures/core.md) +Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:477`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -125,7 +125,7 @@ The agent's session lifecycle began, fired once before its first turn. `source` Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:305`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -137,7 +137,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:329`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:281`](../../packages/core/agent/src/types.ts) ### `agent/step-result` — waterfall @@ -149,7 +149,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:487`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:430`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -161,7 +161,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:500`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:443`](../../packages/core/agent/src/types.ts) ## `fs/*` diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index c5249d4859..13692dad9e 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -130,8 +130,8 @@ interface GenerateOptions { /** * Ordered conversation messages, exactly as the provider sees them (after * the `system` slot). A loop-built request assembles them as - * `EpochHeader.messagePrefix` + the derived history + `messageSuffix` - * (dsh-agent-loop); a hand-built one-shot passes any list. + * `EpochHeader.messagePrefix` + the derived history (dsh-agent-loop); a + * hand-built one-shot passes any list. */ messages: Message[] /** System prompt text (adapters map to the provider's system slot). */ @@ -193,9 +193,9 @@ The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` ### The request envelope: `LlmCallConfig` and the logged header -Requests are built by the loop, not shaped per call: the non-history half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt, the tool schemas in the assembly's canonical order (dsh-system-prompt's `toolOrder` config, lexicographic when unset), and any request-only advice messages — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling; the `agent/request-advice` waterfall weaves request-only advice around the derived history (recorded as the header's `messagePrefix`/`messageSuffix`) — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws. +Requests are built by the loop, not shaped per call: the non-history half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt, the tool schemas in the assembly's canonical order (dsh-system-prompt's `toolOrder` config, lexicographic when unset), and the session prefix — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling; the `agent/session-prefix` waterfall — fired once per loop instance — composes the request-only messages fronting the derived history (recorded as the header's `messagePrefix`) — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws. -On the wire, a loop-built request reads in this order: the `system` slot (the rendered prompt assembly) → `messagePrefix` (the request-only `before` advice) → the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps — → `messageSuffix` (the request-only `after` advice, the last thing the model reads). The advice arrays never enter the derived history; their durable record is the header events, and the dev invariant recomputes exactly this equation against every loop-built request. +On the wire, a loop-built request reads in this order: the `system` slot (the rendered prompt assembly) → `messagePrefix` (the frozen session prefix) → the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The prefix never enters the derived history; its durable record is the header events, and the dev invariant recomputes exactly this equation against every loop-built request. FIXME(call-config-shape): revisit the exact definition of this type — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit here out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them. @@ -328,7 +328,7 @@ interface Agent { } ``` -`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`) is merge-extensible — plugins add creation options by declaration merging; the persona is NOT an agent option but the `dsh-system-prompt` plugin's `persona` config, shared context-wide. The `agent/*` event taxonomy (lifecycle emits incl. `agent/session-start`, the serial `agent/pre-step` surface-mutation seam, and the `agent/prompt-submit`/`agent/request`/`agent/request-advice`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy); turn/step boundaries are durable `session/event` records, not `agent/*` emits. +`AgentStatus` is `'idle' | 'running' | 'disposed'`. `AgentId` is a branded string. `AgentOptions` (`model?`) is merge-extensible — plugins add creation options by declaration merging; the persona is NOT an agent option but the `dsh-system-prompt` plugin's `persona` config, shared context-wide. The `agent/*` event taxonomy (lifecycle emits incl. `agent/session-start`, the serial `agent/pre-step` surface-mutation seam, and the `agent/prompt-submit`/`agent/request`/`agent/session-prefix`/`agent/step-result`/`agent/turn-continuation` waterfalls) is in [architecture.md § Event taxonomy](../architecture.md#event-taxonomy); turn/step boundaries are durable `session/event` records, not `agent/*` emits. ## Interception decisions @@ -365,35 +365,7 @@ type ContinuationDecision = type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact' ``` -`agent/request-advice` returns a `RequestAdvice` — the request-only advice woven around the derived history for ONE request (advice in both senses: advisory content for the model, attached before/after the join point like AOP advice, never modifying the history itself). Concretely, per request: `before` messages sit in front of the ENTIRE derived history, directly after the system slot — the conventional home for session-stable openers like an AGENTS.md digest or a skills catalog, re-contributed identically every step so the provider prefix cache holds; `after` messages follow the history's last message, closing the request. Not a Decision union: the seam contributes content instead of vetoing, so the shape is the contribution itself; the loop records the non-empty arrays as the header's `messagePrefix`/`messageSuffix` ([the request envelope](#the-request-envelope-llmcallconfig-and-the-logged-header)), and `deriveMessages()` never returns them: - -```ts type-equiv -interface RequestAdvice { - /** Before-advice: messages placed ahead of the entire derived history. */ - before: Message[] - /** After-advice: messages placed after the derived history's last message. */ - after: Message[] -} -``` - -Listeners read the already-fixed request facts from a `RequestAdviceContext` (decide what to contribute from these; never mutate them): - -```ts type-equiv -interface RequestAdviceContext { - /** The rendered system prompt this request will carry. */ - system: string - /** The prompt assembly the system prompt was rendered from (sections + tools). */ - assembly: PromptAssembly - /** - * The boundary snapshot: the derived history this request will carry between - * `before` and `after`. A frozen snapshot — treat it as read-only; content - * for the NEXT request flows through the log channels. - */ - boundaryMessages: readonly Message[] - /** Aborts in-flight listener work when the step is torn down. */ - signal: AbortSignal -} -``` +`agent/session-prefix` composes the session prefix — a plain `Message[]`, no dedicated payload type. Fired ONCE per loop instance, lazily on its first request: the composed list is deep-frozen, recorded as the header's `messagePrefix` ([the request envelope](#the-request-envelope-llmcallconfig-and-the-logged-header)), and placed in front of the ENTIRE derived history on every request the instance sends — the home for session-stable openers like a skills catalog or an AGENTS.md digest, never returned by `deriveMessages()`. Reuse is structural, so the prefix cannot drift mid-session (resume = a new instance = a recompose); content that changes mid-session goes through the append-only history channels instead (`agent.inject()`, `tools/post-execute` / prompt-submit `additionalContext`). Not a Decision union: the seam contributes content instead of vetoing, so the shape is the contribution itself. ## `ToolDefinition` diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index e1f29882e5..1b12c3fc48 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -75,14 +75,14 @@ interface SessionEventMap { 'request/header': { header: EpochHeader; reason: RequestHeaderReason } /** * Amendment to the folded {@link EpochHeader}: system line-trim, name-keyed - * tools delta, whole replacement config, or whole replacement request-only - * message arrays (an EMPTY array encodes the transition to "none"). The + * tools delta, whole replacement config, or whole replacement session + * prefix (an EMPTY array encodes the transition to "none"). The * writer verifies `applyHeaderDelta(previous, delta)` reproduces the new * header exactly and falls back to a `'fallback'` `request/header` snapshot * when it cannot, so a logged delta ALWAYS round-trips. NOT a * {@link SurfaceEventType}. */ - 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[]; messageSuffix?: Message[] } + 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } } ``` @@ -99,7 +99,7 @@ export interface TodoItem { ### The request header events: `request/header` and `request/header-delta` -The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas + request-only messages) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A `request/header` snapshot (reason `'initial' | 'resume' | 'fallback'`) anchors the fold at conversation birth, process boundaries, and delta-encoding fallbacks; `request/header-delta` events amend it mid-run. `foldRequestHeader(events)` reconstructs the header any request was built under; the writer round-trip-verifies every delta before logging it, so a well-formed log always folds. Neither is a `SurfaceEventType` — they produce no LLM message. +The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas + the session prefix) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A `request/header` snapshot (reason `'initial' | 'resume' | 'fallback'`) anchors the fold at conversation birth, process boundaries, and delta-encoding fallbacks; `request/header-delta` events amend it mid-run. `foldRequestHeader(events)` reconstructs the header any request was built under; the writer round-trip-verifies every delta before logging it, so a well-formed log always folds. Neither is a `SurfaceEventType` — they produce no LLM message. ```ts type-equiv export interface EpochHeader { @@ -110,18 +110,17 @@ export interface EpochHeader { /** Assembled tool schemas; absent for a tool-less request. */ tools?: ToolSchema[] /** - * Request-only messages sent BEFORE the derived history (the - * `agent/request-advice` waterfall's `before` contributions). Not session - * history — `deriveMessages()` never returns them — so the header is their - * only durable record; absent when the request carried none. + * The session prefix: request-only messages sent BEFORE the entire derived + * history (the `agent/session-prefix` waterfall's product, composed once + * per loop instance and reused for every request it sends). Not session + * history — `deriveMessages()` never returns it — so the header is its + * only durable record; absent when the instance composed none. */ messagePrefix?: Message[] - /** Request-only messages sent AFTER the derived history; absent when none. */ - messageSuffix?: Message[] } ``` -Canonical form: an empty system prompt, an empty tool list, and empty request-only message arrays are ABSENT fields, matching how requests are built. `messagePrefix`/`messageSuffix` are the durable record of the `agent/request-advice` waterfall's contributions (the request is `messagePrefix + derived history + messageSuffix`); their deltas replace the array whole, an empty array encoding the transition back to absence. The other delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). +Canonical form: an empty system prompt, an empty tool list, and an empty session prefix are ABSENT fields, matching how requests are built. `messagePrefix` is the durable record of the `agent/session-prefix` waterfall's product (the request is `messagePrefix + derived history`); composed once per loop instance and anchored by that instance's snapshot, so the loop never produces a prefix delta in practice — the delta arm (whole-array replacement, an empty array encoding the transition back to absence) exists for codec totality. The other delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). ## `SessionEvent` — one log entry diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 02bad3d6c8..834dfc6d69 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -7,18 +7,18 @@ 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:313`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:320`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:512`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:398`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:411`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:338`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:435`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/request-advice` | `waterfall` | [`packages/core/agent/src/types.ts:477`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:353`](../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:329`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:487`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:500`](../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/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:455`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:350`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:363`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:290`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:387`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:305`](../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:281`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | +| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:430`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:443`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../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:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 5c0ddd2ca1..16ef2fb583 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -23,7 +23,7 @@ Raw stream chunk — token-level replay fidelity. Types: [StreamChunk](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:313`](../packages/core/session/src/types.ts) #### `assistant/message` — surface @@ -35,7 +35,7 @@ Assembled assistant message for one step (derived history uses this). Carries th Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:322`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:320`](../packages/core/session/src/types.ts) ### `compact/*` @@ -83,7 +83,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:313`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:311`](../packages/core/session/src/types.ts) ### `hook/*` @@ -119,7 +119,7 @@ A queued prompt an `agent/prompt-submit` listener VETOED — the durable record Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:307`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:305`](../packages/core/session/src/types.ts) ### `request/*` @@ -131,14 +131,14 @@ Full snapshot of the EpochHeader the NEXT request is built under, with the Reque 'request/header': { header: EpochHeader; reason: RequestHeaderReason } ``` -Source: [`packages/core/session/src/types.ts:367`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:365`](../packages/core/session/src/types.ts) #### `request/header-delta` — log-only -Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta, a whole replacement LlmCallConfig (four scalars — not worth diffing), or a whole replacement request-only message array (`messagePrefix`/`messageSuffix` — small advisory content, replaced whole; an EMPTY array encodes the transition to "none", mirroring the canonical form's absent field). Appended by the loop inside the step, before dispatch, when the header for this request differs from the fold of the log so far; the writer verifies `applyHeaderDelta(previous, delta)` reproduces the new header exactly and falls back to a `'fallback'` `request/header` snapshot when it cannot, so a logged delta ALWAYS round-trips. NOT a SurfaceEventType. +Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta, a whole replacement LlmCallConfig (four scalars — not worth diffing), or a whole replacement session prefix (`messagePrefix` — small advisory content, replaced whole; an EMPTY array encodes the transition to "none", mirroring the canonical form's absent field — the loop never produces one in practice: the prefix is composed once per instance and anchored by that instance's snapshot, so this arm exists for codec totality). Appended by the loop inside the step, before dispatch, when the header for this request differs from the fold of the log so far; the writer verifies `applyHeaderDelta(previous, delta)` reproduces the new header exactly and falls back to a `'fallback'` `request/header` snapshot when it cannot, so a logged delta ALWAYS round-trips. NOT a SurfaceEventType. ```ts persistence-catalog -'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[]; messageSuffix?: Message[] } +'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } ``` Source: [`packages/core/session/src/types.ts:382`](../packages/core/session/src/types.ts) @@ -155,7 +155,7 @@ Steering content injected between steps of a running turn. Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:340`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:338`](../packages/core/session/src/types.ts) ### `step/*` @@ -167,7 +167,7 @@ Closes step `step` of turn `turn`. 'step/end': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:294`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:292`](../packages/core/session/src/types.ts) #### `step/start` — log-only @@ -177,7 +177,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it 'step/start': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:292`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts) ### `todo/*` @@ -193,7 +193,7 @@ NOT a SurfaceEventType: it produces no LLM message and never reaches `deriveMess Types: [TodoItem](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:354`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:352`](../packages/core/session/src/types.ts) ### `tool/*` @@ -207,7 +207,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st Types: [CallId](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:328`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:326`](../packages/core/session/src/types.ts) #### `tool/result` — surface @@ -219,7 +219,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:338`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:336`](../packages/core/session/src/types.ts) ### `turn/*` @@ -233,7 +233,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai Types: [TurnEndReason](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:288`](../packages/core/session/src/types.ts) #### `turn/start` — log-only @@ -245,7 +245,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch Types: [TurnTrigger](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:284`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:282`](../packages/core/session/src/types.ts) ### `user/*` @@ -259,4 +259,4 @@ A user-visible prompt (queued message drained at turn start). Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:294`](../packages/core/session/src/types.ts) diff --git a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md index e2bb16438a..20bd1e3005 100644 --- a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -20,13 +20,13 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro **Messages.** `Session.deriveMessages()` is cached: each surface node is projected exactly once, when first seen, through the public per-node function `deriveEventMessage(event)`; a surface rewrite (a compaction `replace` — `SurfaceManager.replaceGeneration`) rebuilds. Callers get a fresh array per call over shared, deep-frozen messages: mutating logged history through a projection is unrepresentable (it throws), replacing the old clone-per-call isolation. External reconstructors fold the same public function over a log prefix, so no two paths can disagree. -**The header.** The request's non-history half — `EpochHeader`: call config (`LlmCallConfig`: model + sampling scalars), rendered system prompt, assembled tool schemas, and any request-only messages (`messagePrefix`/`messageSuffix`, below) — is logged session state, in canonical form (empty system/tools/message arrays ≡ absent). Two log-only, turn-enclosed events in dsh-session carry it: `request/header`, a full snapshot with reason `'initial' | 'resume' | 'fallback'`, and `request/header-delta`, an amendment (`SystemDelta`: a common-prefix/suffix line trim; `ToolsDelta`: name-keyed added/removed/changed; `config`: replaced whole; `messagePrefix`/`messageSuffix`: replaced whole, an empty array encoding the transition to absence). The pure trio `foldRequestHeader` / `diffHeader` / `applyHeaderDelta` reconstructs; the live session tracks the fold with the same lazy cursor as the message cache. Snapshots anchor the fold where a fold needs anchors — conversation birth and process boundaries — and each loop instance appends one on its first request (`'initial'` when the log has none, `'resume'` otherwise, even when nothing changed: the boundary itself is a recorded fact, and cross-restart drift becomes attributable while an unchanged header resumes byte-identical). Deltas are an encoding optimization with a safety valve, never a correctness dependency: the writer verifies `applyHeaderDelta(prev, delta)` reproduces the new header exactly and records a `'fallback'` snapshot when the encoding cannot express a change (a pure tool reordering), so a well-formed log always folds. +**The header.** The request's non-history half — `EpochHeader`: call config (`LlmCallConfig`: model + sampling scalars), rendered system prompt, assembled tool schemas, and the session prefix (`messagePrefix`, below) — is logged session state, in canonical form (empty system/tools/prefix ≡ absent). Two log-only, turn-enclosed events in dsh-session carry it: `request/header`, a full snapshot with reason `'initial' | 'resume' | 'fallback'`, and `request/header-delta`, an amendment (`SystemDelta`: a common-prefix/suffix line trim; `ToolsDelta`: name-keyed added/removed/changed; `config`: replaced whole; `messagePrefix`: replaced whole, an empty array encoding the transition to absence — an arm the loop never exercises in practice, kept for codec totality). The pure trio `foldRequestHeader` / `diffHeader` / `applyHeaderDelta` reconstructs; the live session tracks the fold with the same lazy cursor as the message cache. Snapshots anchor the fold where a fold needs anchors — conversation birth and process boundaries — and each loop instance appends one on its first request (`'initial'` when the log has none, `'resume'` otherwise, even when nothing changed: the boundary itself is a recorded fact, and cross-restart drift becomes attributable while an unchanged header resumes byte-identical). Deltas are an encoding optimization with a safety valve, never a correctness dependency: the writer verifies `applyHeaderDelta(prev, delta)` reproduces the new header exactly and records a `'fallback'` snapshot when the encoding cannot express a change (a pure tool reordering), so a well-formed log always folds. -**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → the `agent/request-advice` waterfall — request-ONLY `before`/`after` messages framing the boundary snapshot (a frozen empty seed, contributions returned as an extension of `next()`; the per-request advisory channel: content the model must see now that must NOT become history — a skills catalog, an environment reminder) — → the header event the request owes the log, carrying those contributions as `messagePrefix`/`messageSuffix` (no session event carries them, so the header is their only durable record) → build `GenerateOptions` from `messagePrefix + snapshot + messageSuffix` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's only in-process bookkeeping is one boolean: whether this instance has logged its anchoring snapshot. +**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → on the instance's FIRST request only, the `agent/session-prefix` waterfall — request-ONLY messages fronting the entire derived history (a frozen empty seed, contributions returned as an extension of `next()`; the home for session-stable openers that must NOT become history — a skills catalog, an AGENTS.md digest), deep-frozen and cached on the instance so reuse is structural and the prefix cannot drift mid-session — → the header event the request owes the log, carrying the prefix as `messagePrefix` (no session event carries it, so the header is its only durable record; resume = a new instance = a recompose, anchored by its `'resume'` snapshot) → build `GenerateOptions` from `messagePrefix + snapshot` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's per-instance bookkeeping is one boolean plus the cached prefix: whether this instance has logged its anchoring snapshot, and what it composed. **The reconstruction boundary is `step/start`, unconditionally.** A step's messages are the derivation over `events[0..stepStartSeq)`. Because the snapshot precedes the `step/start` append in the same synchronous frame, nothing can enter this request past the boundary: an `agent.inject()` from an `agent/request` listener (or any concurrent task, or a `session/event` listener firing on `step/start` itself) lands in the log after the boundary and joins the NEXT request. For waterfall-window appends this matches the prior loop (it also derived before its waterfall); for a synchronous `step/start` listener it is a deliberate change — such a listener could previously reach the current request — and `agent/pre-step` is the sanctioned seam for content that must affect the CURRENT request. A step's header for reconstruction is the fold after its own `request/header*` event (which sits between its `step/start` and first response event) or the fold carried forward. -**Enforcement.** Dev-mode ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)), on `llm/stream`: a frozen request with a live `sessionId` — the loop-built marker; hand-built one-shots are unfrozen and skipped — must carry messages deep-equal to the folded header's `messagePrefix`, then the boundary derivation, then its `messageSuffix` — the derivation rebuilt through a FRESH `Session` over `events[0..stepStartSeq)` so the live cache cannot vouch for itself — and header fields equal to `foldRequestHeader` over the log. There is no divergence allowance and nothing to allow: no seam can put unlogged content into a request — the `agent/request-advice` seam's contributions enter only because the header event records them first. `prepend: true` only defends against the replay adapter's short-circuit (an append-registered listener); two prepended listeners have no defined mutual order in cordis, so correctness rests on the seq-bounded fold, never on listener timing. Measurement stays lean: the with-key e2e ([request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts)) proves `usage.cacheReadTokens > 0` on every request after the first against the live API, and per-step usage in the log is the production observable — a header event or compaction shows up as a cache-read collapse on the next step. +**Enforcement.** Dev-mode ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)), on `llm/stream`: a frozen request with a live `sessionId` — the loop-built marker; hand-built one-shots are unfrozen and skipped — must carry messages deep-equal to the folded header's `messagePrefix` followed by the boundary derivation — the derivation rebuilt through a FRESH `Session` over `events[0..stepStartSeq)` so the live cache cannot vouch for itself — and header fields equal to `foldRequestHeader` over the log. There is no divergence allowance and nothing to allow: no seam can put unlogged content into a request — the `agent/session-prefix` seam's product enters only because the header event records it first. `prepend: true` only defends against the replay adapter's short-circuit (an append-registered listener); two prepended listeners have no defined mutual order in cordis, so correctness rests on the seq-bounded fold, never on listener timing. Measurement stays lean: the with-key e2e ([request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts)) proves `usage.cacheReadTokens > 0` on every request after the first against the live API, and per-step usage in the log is the production observable — a header event or compaction shows up as a cache-read collapse on the next step. ### The MiniCode shape: adopted, with the provenance arrow inverted @@ -44,7 +44,7 @@ What survives from `LLMClient`: the conversation is maintained, not rebuilt — ## Consequences - A request that is not explained by the log cannot be constructed by accident — not by the loop, not by a listener; mutating a built request throws; every header change is a durable, diffable log event. -- Choosing between the advisory channels is a change-frequency cost decision, and the seam does not hide it: an `agent/request-advice` contribution rides the request's uncached tail and is re-tokenized at full price on every request it appears in (a `before` contribution instead extends the cacheable prefix at zero marginal cost while stable, but a mid-session change invalidates the provider cache for the entire history after it), whereas an `inject()`ed `context/message` is paid once and prefix-cached thereafter at the price of accumulating durably in history and the log. Route session-frozen content to `before`, low-frequency change notices to `inject()`, and reserve `after` for small, frequently refreshed state snapshots where a durable chain of stale copies would bloat the log and mislead the model. +- Choosing between the advisory channels is a change-frequency decision, and the design makes the stable one structural: an `agent/session-prefix` contribution is composed once per loop instance and reused verbatim, so it extends the cacheable prefix at zero marginal cost and CANNOT bust the provider cache mid-session; content that changes mid-session flows through the append-only history channels — `agent.inject()`, a `tools/post-execute` decision's `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter, at the price of accumulating in history and the log. Route session-frozen openers to the prefix and change notices to the history channels; a per-step request-only tail slot was deliberately dropped (no consumer, and a durable append covers every current update pattern). - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replace node), a real prompt/tool change (`request/header-delta`), a config switch (ditto), a process boundary with drift (`'resume'` snapshot differing from its predecessor). The provider's own reasoning-content exclusion is managed server-side. - The `step/start`-listener behavior change (above) is the one observable semantics change for plugins; `agent/pre-step` is the current-request seam. - Tool-result trimming (planned) needs no new mechanism: a logged single-node surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic. diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index ebdcc7d91a..d4c1c50466 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -59,10 +59,10 @@ forever: boundary = session.deriveMessages() ⟵ reconstruction boundary: same sync frame, session('step/start') strictly before step/start config = waterfall agent/request ⟵ frozen seed; return a replacement to switch - reqMsgs = waterfall agent/request-advice ⟵ request-only before/after messages; recorded - on the header, never session history + prefix ??= waterfall agent/session-prefix ⟵ once per instance (first request): frozen + session prefix; on the header, never history session('request/header'[-delta]) ⟵ the header event this request owes the log - stream llm.stream(freeze({header..., messages: before+boundary+after})) → session('assistant/chunk') + stream llm.stream(freeze({header..., messages: prefix+boundary})) → session('assistant/chunk') message = waterfall agent/step-result session('assistant/message') each tool-call: session('tool/call') @@ -86,7 +86,7 @@ Cancellation: `agent.cancel()` is the single public stop primitive — it clears ### What is NOT here Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy: -- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/request-advice`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` +- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/session-prefix`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation` - Compaction: `agent/pre-step` - Sandbox, permission, plan mode: `tools/pre-execute` (deny/ask gate), `tools/post-execute` - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred. diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index 9170de4836..753da50db7 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -10,7 +10,7 @@ import type { Context } from 'cordis' import type { FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm' import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm' -import type { ContinuationDecision, HookContext, PromptDecision, RequestAdvice } from '@deepseek-ai/dsh-agent' +import type { ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session' import { createTransmissionLog, recordRequestHeader } from './request-log.ts' @@ -161,11 +161,12 @@ export interface LoopHandle { * boundary = session.deriveMessages() ⟵ the reconstruction boundary: snapshot in the * session('step/start') same sync frame, strictly before step/start * config = waterfall agent/request(config) ⟵ frozen seed; a returned replacement switches - * advice = waterfall agent/request-advice ⟵ request-only before/after advice; logged on - * the header, never session history + * prefix ??= waterfall agent/session-prefix ⟵ once per loop instance (first request): + * frozen session prefix; logged on the header, + * never session history * session('request/header'|'request/header-delta') ⟵ the header event this request owes the * log (initial/resume anchor, delta, fallback) - * req = freeze({header..., messages: before+boundary+after, sessionId, signal}) + * req = freeze({header..., messages: prefix+boundary, sessionId, signal}) * stream ctx.llm.stream(req) ⟵ waterfall llm/stream (raw chunks, frozen req) * session('assistant/chunk') * msg = waterfall agent/step-result ⟵ BEFORE the log append, so the @@ -676,8 +677,9 @@ function drainSteering(agent: ReactLoopAgent, turn: number): boolean { } /** One step: build the request from the boundary snapshot + the step's - * header → collect request-only messages → log the header event the request - * owes → stream model → record → execute tools. The caller assembles the + * header → compose the session prefix if this instance has none yet → log + * the header event the request owes → stream model → record → execute + * tools. The caller assembles the * system prompt, fires the `agent/pre-step` seam, snapshots the derivation, * and opens the step BEFORE calling this, so `boundaryMessages` is exactly * the surface prefix at step/start and already reflects any compaction. */ @@ -720,47 +722,47 @@ async function runStep( throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`) } - // Collect the request-ONLY advice: `before` messages go in front of the - // entire boundary snapshot, `after` messages follow its last message. Advice - // is not session history — the header event below is its only durable - // record (EpochHeader.messagePrefix/messageSuffix), which keeps the request - // a pure function of the log. The frozen empty seed serves both the - // listener chain and the no-listener fallback: a contribution is a RETURNED - // extension of `await next()`, never an in-place push. The context gets a - // frozen COPY of the boundary (the request is built from the internal - // snapshot), so a listener cannot smuggle unlogged content into the request - // by mutating what it was shown. Fired AFTER the boundary snapshot, so a - // listener's session append lands past the boundary and joins the NEXT - // request — the same window rule as the `agent/request` waterfall. - const emptyRequestAdvice: RequestAdvice = deepFreeze({ before: [], after: [] }) - const requestAdviceBoundary = deepFreeze([...boundaryMessages]) - const requestAdvice = await ctx.waterfall( - 'agent/request-advice', agent, turn, step, emptyRequestAdvice, - { system, assembly, boundaryMessages: requestAdviceBoundary, signal }, - () => Promise.resolve(emptyRequestAdvice), - ) + // Compose the session prefix ONCE per loop instance, lazily on its first + // request-building step: request-only messages placed in front of the + // ENTIRE derived history on every request this instance sends. The result + // is deep-cloned (decoupled from listener-held references), deep-frozen, + // and cached on the transmission bookkeeping, so reuse is structural — the + // prefix cannot change mid-session and the provider prefix cache holds by + // construction (resume = a new instance = a recompose, anchored by its + // 'resume' snapshot). The prefix is not session history — the header event + // below is its only durable record (EpochHeader.messagePrefix), which + // keeps the request a pure function of the log. The frozen empty seed + // serves both the listener chain and the no-listener fallback: a + // contribution is a RETURNED extension of `await next()`, never an + // in-place push. + if (transmission.sessionPrefix === undefined) { + const emptyPrefix: Message[] = deepFreeze([]) + transmission.sessionPrefix = deepFreeze(structuredClone(await ctx.waterfall( + 'agent/session-prefix', agent, emptyPrefix, signal, + () => Promise.resolve(emptyPrefix), + ))) + } + const sessionPrefix = transmission.sessionPrefix // The request header (the log's request/header* vocabulary): canonical form, // recorded before dispatch so the log always explains the request — - // including the request-only advice, which no other event carries. + // including the session prefix, which no other event carries. const header = canonicalHeader({ config, ...system ? { system } : {}, ...assembly.tools.length > 0 ? { tools: assembly.tools } : {}, - ...requestAdvice.before.length > 0 ? { messagePrefix: requestAdvice.before } : {}, - ...requestAdvice.after.length > 0 ? { messageSuffix: requestAdvice.after } : {}, + ...sessionPrefix.length > 0 ? { messagePrefix: sessionPrefix } : {}, }) recordRequestHeader(session, transmission, header) // Build and freeze: the request is a pure function of (boundary snapshot, // logged header) — llm/stream listeners and adapters read it, mutation // throws. sessionId + frozen is the loop-built marker the dev invariant - // keys on. Message order: header.messagePrefix, then the boundary snapshot, - // then header.messageSuffix — the reconstruction equation the invariant - // recomputes. + // keys on. Message order: header.messagePrefix, then the boundary + // snapshot — the reconstruction equation the invariant recomputes. const request: GenerateOptions = deepFreeze({ model: header.config.model, - messages: [...header.messagePrefix ?? [], ...boundaryMessages, ...header.messageSuffix ?? []], + messages: [...header.messagePrefix ?? [], ...boundaryMessages], ...header.system !== undefined ? { system: header.system } : {}, ...header.tools !== undefined ? { tools: header.tools } : {}, ...header.config.temperature !== undefined ? { temperature: header.config.temperature } : {}, diff --git a/packages/core/agent-loop/src/request-log.ts b/packages/core/agent-loop/src/request-log.ts index 90f47068fa..d2763f5c2a 100644 --- a/packages/core/agent-loop/src/request-log.ts +++ b/packages/core/agent-loop/src/request-log.ts @@ -12,11 +12,20 @@ import { diffHeader, headerEquals, applyHeaderDelta } from '@deepseek-ai/dsh-session' import type { EpochHeader, Session } from '@deepseek-ai/dsh-session' +import type { Message } from '@deepseek-ai/dsh-llm' /** Per-loop-instance bookkeeping: whether THIS instance has logged a header yet. */ export interface TransmissionLog { /** True once this loop instance appended its anchoring `request/header` snapshot. */ loggedHeader: boolean + /** + * The instance's composed session prefix (the `agent/session-prefix` + * waterfall's deep-frozen product), cached on the instance's first + * request-building step and reused verbatim for every request it sends — + * the structural guarantee that the prefix never changes mid-session. + * `undefined` until composed. + */ + sessionPrefix?: Message[] } /** @@ -61,7 +70,7 @@ export function recordRequestHeader(session: Session, state: TransmissionLog, he const baseline = session.requestHeader()! if (headerEquals(baseline, header)) return const delta = diffHeader(baseline, header) - /* v8 ignore next -- headerEquals false ⟹ diffHeader defined: both compare the same three parts */ + /* v8 ignore next -- headerEquals false ⟹ diffHeader defined: both compare the same four parts */ if (delta === undefined) return if (headerEquals(applyHeaderDelta(baseline, delta), header)) { session.append('request/header-delta', delta) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index f980b2337c..c3f301afc7 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -1,14 +1,13 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import LlmService, { CallId, type Message } from '@deepseek-ai/dsh-llm' -import SessionStore, { foldRequestHeader, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' +import SessionStore, { type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools' import AgentRegistry, { AgentId, type ContinuationDecision, type PromptDecision, - type RequestAdvice, type SessionStartSource, } from '@deepseek-ai/dsh-agent' import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' @@ -311,58 +310,58 @@ describe('agent/session-start', () => { }) }) -describe('agent/request-advice (RequestAdvice)', () => { - it('frames the derived history: before precedes it, after follows it, and the header records both', async () => { - const adapter = new MockAdapter([textResponse('ok')]) +describe('agent/session-prefix', () => { + it('composes once per loop instance and fronts every request; the header records it; history stays untouched', async () => { + const adapter = new MockAdapter([ + toolCallResponse('c1', 'echo', { text: 'ping' }), + textResponse('done'), + textResponse('again'), + ]) const ctx = await harness(adapter) + ctx.tools.register(defineTool({ + name: 'echo', description: 'echo', parameters: { text: { type: 'string' } }, + async execute(args) { return [{ type: 'text', text: String(args.text) }] }, + })) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'catalog' }] } - const trailer: Message = { role: 'user', content: [{ type: 'text', text: 'trailing note' }] } - ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next): Promise => { - const result = await next() - return { before: [...result.before, reminder], after: [...result.after, trailer] } + let composed = 0 + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { + composed += 1 + return [...await next(), reminder] }) - send(agent, 'hi') + send(agent, 'go') + await waitForIdle(ctx, agent) + send(agent, 'next turn') await waitForIdle(ctx, agent) - // The request carries before + derived history + after, in that order… - const request = adapter.requests[0]! - expect(request.messages).toEqual([ - reminder, - { role: 'user', content: [{ type: 'text', text: 'hi' }] }, - trailer, - ]) - // …the header event is their durable record… - const headerEvent = events(agent).find(e => e.type === 'request/header') - expect(headerEvent?.type === 'request/header' && headerEvent.data.header.messagePrefix).toEqual([reminder]) - expect(headerEvent?.type === 'request/header' && headerEvent.data.header.messageSuffix).toEqual([trailer]) - // …and they never become session history. - expect(agent.session.deriveMessages()).toEqual([ - { role: 'user', content: [{ type: 'text', text: 'hi' }] }, - { role: 'assistant', content: [{ type: 'text', text: 'ok' }] }, - ]) + // Three requests (two turns), ONE composition: the frozen product is + // reused verbatim, so the prefix cannot drift mid-session. + expect(adapter.requests).toHaveLength(3) + expect(composed).toBe(1) + for (const request of adapter.requests) { + expect(request.messages[0]).toEqual(reminder) + } + // The anchoring snapshot is the prefix's durable record — and the ONLY + // header event: reuse means no request/header-delta ever. + const headerEvents = events(agent).filter(e => e.type === 'request/header' || e.type === 'request/header-delta') + expect(headerEvents).toHaveLength(1) + expect(headerEvents[0]?.type === 'request/header' && headerEvents[0].data.header.messagePrefix).toEqual([reminder]) + // Never session history: the derivation starts at the real user prompt. + expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] }) }) - it('contributions compose across listeners and see the read-only request facts', async () => { + it('contributions compose across listeners in registration order', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - const seen: { system: string; boundaryRoles: string[]; sectionCount: number }[] = [] - ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, context, next): Promise => { - const result = await next() - seen.push({ - system: context.system, - boundaryRoles: context.boundaryMessages.map(m => m.role), - sectionCount: context.assembly.sections.length, - }) - return { before: [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...result.before], after: result.after } + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { + return [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...await next()] }) - ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next): Promise => { - const result = await next() - return { before: [...result.before, { role: 'user', content: [{ type: 'text', text: 'second' }] }], after: result.after } + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { + return [...await next(), { role: 'user', content: [{ type: 'text', text: 'second' }] }] }) send(agent, 'hi') @@ -372,27 +371,21 @@ describe('agent/request-advice (RequestAdvice)', () => { // out (waterfall), so its prepend lands first. const texts = adapter.requests[0]!.messages.map(m => m.content[0]?.type === 'text' ? m.content[0].text : '') expect(texts).toEqual(['first', 'second', 'hi']) - // The context carried the request facts: the rendered system prompt, the - // boundary snapshot (exactly the drained user prompt), and the assembly. - expect(seen).toHaveLength(1) - expect(seen[0]!.boundaryRoles).toEqual(['user']) - expect(typeof seen[0]!.system).toBe('string') }) - it('with no contributions the header omits both fields and the request is the bare derivation', async () => { + it('with no contributions the header omits messagePrefix and the request is the bare derivation', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) // A listener that delegates without contributing — the canonical no-op. - ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next) => next()) + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => next()) send(agent, 'hi') await waitForIdle(ctx, agent) const headerEvent = events(agent).find(e => e.type === 'request/header') expect(headerEvent?.type === 'request/header' && 'messagePrefix' in headerEvent.data.header).toBe(false) - expect(headerEvent?.type === 'request/header' && 'messageSuffix' in headerEvent.data.header).toBe(false) expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) }) @@ -402,9 +395,9 @@ describe('agent/request-advice (RequestAdvice)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let mutationError: unknown - ctx.on('agent/request-advice', async (_agent, _turn, _step, messages, _context, next): Promise => { + ctx.on('agent/session-prefix', async (_agent, prefix, _signal, next): Promise => { try { - messages.before.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) + prefix.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) } catch (error: unknown) { mutationError = error } @@ -418,30 +411,7 @@ describe('agent/request-advice (RequestAdvice)', () => { expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) }) - it('the read-only boundary context rejects in-place mutation before the request is built', async () => { - const adapter = new MockAdapter([textResponse('ok')]) - const ctx = await harness(adapter) - const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - - let mutationError: unknown - ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, context, next): Promise => { - try { - const mutableBoundary = context.boundaryMessages as Message[] - mutableBoundary.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] }) - } catch (error: unknown) { - mutationError = error - } - return next() - }) - - send(agent, 'hi') - await waitForIdle(ctx, agent) - - expect(mutationError).toBeInstanceOf(TypeError) - expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }]) - }) - - it('a per-step contribution change is logged as a header delta, so every request stays reconstructable', async () => { + it('mutating a listener-held reference after composition cannot alter later requests (the cache is a frozen clone)', async () => { const adapter = new MockAdapter([ toolCallResponse('c1', 'echo', { text: 'ping' }), textResponse('done'), @@ -453,26 +423,21 @@ describe('agent/request-advice (RequestAdvice)', () => { })) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - let step = 0 - ctx.on('agent/request-advice', async (_agent, _turn, _step, _messages, _context, next): Promise => { - const result = await next() - step += 1 - return { before: [...result.before, { role: 'user', content: [{ type: 'text', text: `reminder v${step}` }] }], after: result.after } - }) + const held: Message = { role: 'user', content: [{ type: 'text', text: 'v1' }] } + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => [...await next(), held]) send(agent, 'go') await waitForIdle(ctx, agent) - expect(adapter.requests[0]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'reminder v1' }] }) - expect(adapter.requests[1]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'reminder v2' }] }) - // Step 2's changed prefix rides a request/header-delta whose fold matches - // what the second request actually sent. - const delta = events(agent).find(e => e.type === 'request/header-delta') - expect(delta?.type === 'request/header-delta' && delta.data.messagePrefix).toEqual([{ role: 'user', content: [{ type: 'text', text: 'reminder v2' }] }]) - expect(foldRequestHeader(agent.session.events)?.messagePrefix).toEqual([{ role: 'user', content: [{ type: 'text', text: 'reminder v2' }] }]) + // The listener mutates the object it contributed AFTER composition; the + // cached prefix is a deep-frozen clone, so step 2's request is unchanged. + held.content = [{ type: 'text', text: 'v2' }] + expect(adapter.requests[1]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'v1' }] }) + expect(events(agent).filter(e => e.type === 'request/header-delta')).toHaveLength(0) }) }) + describe('agent/turn-continuation (ContinuationDecision)', () => { it('a continue decision with a reason records next-step steering in the same turn', async () => { const adapter = new MockAdapter([textResponse('step 1 no tools'), textResponse('step 2')]) diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 0500223369..8a811048c6 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -45,7 +45,7 @@ Turn and step boundaries are NOT mirrored as `agent/*` emits: a consumer that ne - `agent/prompt-submit` — decide what happens to one drained queued message before it becomes a `user/message`: `PromptDecision` = `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (drop it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`). Maps onto Claude Code's `UserPromptSubmit`. - `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step. - `agent/request` — shape the call config before the model call: a frozen `LlmCallConfig` seed in, a replacement out (model switching, sampling overrides). Content is not shapeable here — every request is a pure function of the session log ([reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)); the loop logs whatever config the request actually uses as a `request/header*` event -- `agent/request-advice` — contribute request-ONLY messages around the derived history: a frozen empty `RequestAdvice` seed in, an extension of `await next()` out (`before` messages precede the boundary snapshot in the request, `after` messages follow it). For per-request advisory context the model must see now but that must not become durable history; the loop records the contributions on the request's `request/header*` event (`EpochHeader.messagePrefix`/`messageSuffix`), so `deriveMessages()` stays untouched and the request stays reconstructable. Cost model: contributions ride the request's uncached tail and are re-paid at full price on every request they appear in — put session-frozen content in `before` (cacheable prefix; a mid-session change busts the cache for everything after it), route low-frequency change notices through `agent.inject()` instead (paid once, prefix-cached thereafter), and reserve `after` for small, frequently refreshed state snapshots +- `agent/session-prefix` — compose the session prefix: request-only messages placed in front of the ENTIRE derived history on every request. Fired ONCE per loop instance, lazily on its first request; the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the anchoring `request/header` snapshot, and reused verbatim afterwards — the prefix cannot change mid-session, so the provider prefix cache holds by construction (resume = a new instance = a recompose, attributably anchored by its `'resume'` snapshot). The home for session-stable openers that must not become durable history (a skills catalog, an AGENTS.md digest); `deriveMessages()` never returns it. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, `tools/post-execute` `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter - `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records) - `agent/turn-continuation` — override the continue/stop decision via `ContinuationDecision` = `{action:'stop'}` or `{action:'continue', reason?}` (a `continue` `reason` is recorded as next-step steering in the same turn — the typed `/goal` pattern). Force-continue `/loop`, force-stop budget guard. diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index c35fc0d84e..27af421b17 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -17,7 +17,7 @@ * consumer that wants the live transcript subscribes here. * - **`agent/*`** (this module) — the LIVE runtime surface. Always carries the * live `Agent`. Two shapes: INTERCEPTION seams (the `agent/prompt-submit`/ - * `agent/request`/`agent/request-advice`/`agent/step-result`/ + * `agent/request`/`agent/session-prefix`/`agent/step-result`/ * `agent/turn-continuation` waterfalls and * the serial `agent/pre-step`) that mutate/veto, and TRANSIENT emits * (`agent/status`, `agent/error`, `agent/created`/ @@ -46,7 +46,7 @@ import type { Branded } from '@deepseek-ai/dsh-brand' import type { ContentBlock, LlmCallConfig, Message, MessageSource } from '@deepseek-ai/dsh-llm' -import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt' +import type {} from '@deepseek-ai/dsh-system-prompt' /** Identifies one live agent in the registry. */ export type AgentId = Branded<'AgentId'> @@ -155,54 +155,6 @@ export type ContinuationDecision = | { action: 'stop' } | { action: 'continue'; reason?: HookContext } -/** - * The request-only ADVICE an `agent/request-advice` waterfall listener weaves - * around the derived history of ONE LLM request — advice in both senses: - * advisory content for the model, attached before/after the join point like - * AOP advice, never modifying the history itself. In - * `GenerateOptions.messages` the `before` messages sit in front of the ENTIRE - * derived history (directly after the provider's system slot) and the `after` - * messages follow its last message (the newest user prompt on a turn's first - * step, the previous step's tool results afterwards). Advice is NOT session - * state — nothing here enters the session log as durable history, - * `Session.deriveMessages()` never returns it, and the next step recomputes - * it from scratch. The loop records the non-empty arrays on the request's - * `request/header*` event (`EpochHeader.messagePrefix` / `messageSuffix`), so - * the request stays reconstructable from the log (the reconstructability - * RFC). For content that must become durable conversation history, use the - * log channels instead: `agent.inject()`, steering, or prompt-submit - * `additionalContext`. - */ -export interface RequestAdvice { - /** Before-advice: messages placed ahead of the entire derived history. */ - before: Message[] - /** After-advice: messages placed after the derived history's last message. */ - after: Message[] -} - -/** - * Read-only facts about the request an `agent/request-advice` listener is - * contributing to. Everything here is already fixed when the seam fires: the - * step is open, the boundary snapshot is taken, and the system prompt is - * assembled — a listener uses these to DECIDE what to contribute (e.g. render - * a workspace-dependent reminder, or skip one already present in history), - * never to mutate them. - */ -export interface RequestAdviceContext { - /** The rendered system prompt this request will carry. */ - system: string - /** The prompt assembly the system prompt was rendered from (sections + tools). */ - assembly: PromptAssembly - /** - * The boundary snapshot: the derived history this request will carry between - * `before` and `after`. A frozen snapshot — treat it as read-only; content - * for the NEXT request flows through the log channels. - */ - boundaryMessages: readonly Message[] - /** Aborts in-flight listener work when the step is torn down. */ - signal: AbortSignal -} - /** * Why an agent's session lifecycle began, carried by `agent/session-start`. A * bridge keys its SessionStart hook's matcher on this (Claude Code's @@ -417,7 +369,7 @@ declare module 'cordis' { * session log (the reconstructability RFC), so model-visible content * flows through the log channels — `inject()`, steering, prompt-submit * `additionalContext`, prompt sections via `system-prompt/assemble`, or - * header-logged request-only messages via {@link agent/request-advice} + * the header-logged session prefix via {@link agent/session-prefix} * — never through request mutation, and the loop records whatever config * the request actually uses as a `request/header*` event before dispatch. * The step's messages are already snapshotted when this fires (the @@ -434,47 +386,38 @@ declare module 'cordis' { */ 'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise /** - * Waterfall: weave request-ONLY advice around the derived history — a - * {@link RequestAdvice} whose `before` messages sit in front of the - * ENTIRE boundary snapshot in `GenerateOptions.messages` and whose - * `after` messages follow its last message. Fires once per step, inside - * the open step, after the - * {@link agent/request} config waterfall and before the loop logs the - * request header. This is the seam for per-request advisory context the - * model must see NOW but that must NOT become durable history (a skills - * catalog, an environment reminder): contributions are recorded on the - * request's `request/header*` event (`EpochHeader.messagePrefix` / - * `messageSuffix`) — never as session messages — so - * `Session.deriveMessages()` stays untouched and the request remains - * reconstructable from the log. + * Waterfall: compose the SESSION PREFIX — request-only messages placed in + * front of the ENTIRE derived history (directly after the provider's + * system slot) on every request this loop instance sends. Fired ONCE per + * loop instance, lazily on its first request-building step; the composed + * result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the + * instance's anchoring `'initial'`/`'resume'` header snapshot, and reused + * verbatim for every subsequent request — never recomputed mid-session, + * so the provider prefix cache holds by construction (a process restart + * or `ctx.agents.resume()` is a new instance: it recomposes, and any + * drift lands attributably on the `'resume'` snapshot). * - * The seed is frozen and empty; a contributing listener returns a NEW - * {@link RequestAdvice} extending `await next()` (spread its arrays — - * never mutate them), so contributions compose across plugins in - * registration order. The boundary snapshot is already taken when this - * fires: a `session.append`/`inject()` from a listener here lands in the - * log but joins the NEXT request — contribute through the returned value, - * not the session. Call `next()` to delegate, or return a - * {@link RequestAdvice} without it to short-circuit. + * This is the home for session-stable openers the model must always see + * but that must NOT become durable history — a skills catalog, an + * AGENTS.md digest, a workspace baseline: `Session.deriveMessages()` + * never returns the prefix, and the header events are its only durable + * record, so the request stays reconstructable from the log. Content + * that CHANGES mid-session belongs in the append-only history channels + * instead — `agent.inject()`, a `tools/post-execute` decision's + * `additionalContext`, prompt-submit `additionalContext` — each a + * durable `context/message` paid once and prefix-cached thereafter. * - * Pick the channel by change frequency (the cost model): a contribution - * rides the request's uncached tail, re-tokenized at full price on EVERY - * request it appears in — cheap only while small. Session-FROZEN content - * belongs in `before`, where it extends the cacheable prefix at zero - * marginal cost (but changing it mid-session invalidates the provider - * cache for the entire history after it). A LOW-FREQUENCY change notice - * belongs in durable history via `agent.inject()` — appended once, - * prefix-cached thereafter. Reserve `after` for small, frequently - * refreshed state snapshots, where a durable chain of stale copies would - * bloat the log and mislead the model. - * @param agent - the agent making the model call. - * @param turn - the open turn number. - * @param step - the step whose request this is. - * @param advice - the frozen empty seed; return an extended replacement to contribute. - * @param context - read-only request facts ({@link RequestAdviceContext}). + * The seed is a frozen empty list; a contributing listener returns a NEW + * array extending `await next()` (`[...prefix, mine]` — never an in-place + * push), so contributions compose across plugins in registration order + * and compose deterministically for a fixed plugin set. Call `next()` to + * delegate, or return a list without it to short-circuit. + * @param agent - the agent whose session prefix is being composed. + * @param prefix - the frozen empty seed; return an extended replacement to contribute. + * @param signal - aborts in-flight listener work (e.g. a discovery scan) when the step is torn down. * @mode waterfall */ - 'agent/request-advice'(agent: Agent, turn: number, step: number, advice: RequestAdvice, context: RequestAdviceContext, next: () => Promise): Promise + 'agent/session-prefix'(agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise): Promise /** * Waterfall: post-process the assembled assistant {@link Message} before * tool dispatch (validation, content rewriting, …). diff --git a/packages/core/session/README.md b/packages/core/session/README.md index f032874cbe..1cc393e172 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -51,7 +51,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`. ### Request-header reconstruction (`request-header.ts`) -The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config / whole request-only message arrays) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools/messagePrefix/messageSuffix ≡ absent fields; a delta's EMPTY message array encodes the transition back to absence). `EpochHeader.messagePrefix`/`messageSuffix` are the durable record of the `agent/request-advice` waterfall's request-only contributions — the request is `messagePrefix + derived history + messageSuffix`, and `deriveMessages()` never returns them. +The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config / whole session prefix) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools/messagePrefix ≡ absent fields; a delta's EMPTY prefix array encodes the transition back to absence). `EpochHeader.messagePrefix` is the durable record of the `agent/session-prefix` waterfall's product — composed once per loop instance, the request is `messagePrefix + derived history`, and `deriveMessages()` never returns it. ### Session event vocabulary (`types.ts`) diff --git a/packages/core/session/src/request-header.ts b/packages/core/session/src/request-header.ts index a891237425..eeb2fe40ed 100644 --- a/packages/core/session/src/request-header.ts +++ b/packages/core/session/src/request-header.ts @@ -22,16 +22,14 @@ type HeaderDelta = { tools?: ToolsDelta config?: LlmCallConfig messagePrefix?: Message[] - messageSuffix?: Message[] } /** * Normalize a header to canonical form: an empty system prompt, an empty - * tool list, and empty request-only message arrays become ABSENT fields, - * matching how requests are built (the request-build spreads skip empty - * values). Diff, fold, and comparison all operate on canonical headers, so - * "no system prompt" (and "no request-only messages") has exactly one - * representation. + * tool list, and an empty session prefix become ABSENT fields, matching how + * requests are built (the request-build spreads skip empty values). Diff, + * fold, and comparison all operate on canonical headers, so "no system + * prompt" (and "no session prefix") has exactly one representation. * @param header - the header to normalize (not mutated). * @returns the canonical header. */ @@ -41,7 +39,6 @@ export function canonicalHeader(header: EpochHeader): EpochHeader { ...header.system !== undefined && header.system.length > 0 ? { system: header.system } : {}, ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {}, ...header.messagePrefix !== undefined && header.messagePrefix.length > 0 ? { messagePrefix: header.messagePrefix } : {}, - ...header.messageSuffix !== undefined && header.messageSuffix.length > 0 ? { messageSuffix: header.messageSuffix } : {}, } } @@ -121,22 +118,22 @@ function applyTools(prev: readonly ToolSchema[], delta: ToolsDelta): ToolSchema[ * writer's round-trip guard runs (`applyHeaderDelta(prev, delta)` must equal * the intended header) and the loop runs to skip logging an unchanged header. * Tools compare per-schema IN ORDER (canonical JSON), so a pure reordering is - * correctly unequal; request-only message arrays compare as canonical JSON - * (both sides come from the same build path, so key order matches when the - * values do). + * correctly unequal; the session prefix compares as canonical JSON (both + * sides come from the same build path, so key order matches when the values + * do). * @param a - one canonical header. * @param b - the other. - * @returns whether config, system, tools (in order), and request-only messages all match. + * @returns whether config, system, tools (in order), and the session prefix all match. */ export function headerEquals(a: EpochHeader, b: EpochHeader): boolean { if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false - if (!sameMessages(a.messagePrefix, b.messagePrefix) || !sameMessages(a.messageSuffix, b.messageSuffix)) return false + if (!sameMessages(a.messagePrefix, b.messagePrefix)) return false const at = a.tools ?? [] const bt = b.tools ?? [] return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema)) } -/** Canonical JSON equality over request-only message arrays; absence equals the empty array. */ +/** Canonical JSON equality over session-prefix arrays; absence equals the empty array. */ function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean { return JSON.stringify(a ?? []) === JSON.stringify(b ?? []) } @@ -147,7 +144,7 @@ function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | * ({@link applyHeaderDelta} on `prev` deep-equals `next`) before logging it — * the encoding cannot express every change (a pure tool reordering) — and * fall back to a full `request/header` snapshot when the check fails. - * Request-only messages are replaced whole (small advisory content, not worth + * The session prefix is replaced whole (small advisory content, not worth * diffing); an empty replacement array encodes the transition to "none". * @param prev - the folded header the log currently implies. * @param next - the header the next request will actually use. @@ -161,7 +158,6 @@ export function diffHeader(prev: EpochHeader, next: EpochHeader): HeaderDelta | if (JSON.stringify(prevTools) !== JSON.stringify(nextTools)) delta.tools = diffTools(prevTools, nextTools) if (!callConfigEquals(prev.config, next.config)) delta.config = next.config if (!sameMessages(prev.messagePrefix, next.messagePrefix)) delta.messagePrefix = next.messagePrefix ?? [] - if (!sameMessages(prev.messageSuffix, next.messageSuffix)) delta.messageSuffix = next.messageSuffix ?? [] return Object.keys(delta).length > 0 ? delta : undefined } @@ -177,13 +173,11 @@ export function applyHeaderDelta(prev: EpochHeader, delta: HeaderDelta): EpochHe const system = delta.system !== undefined ? applySystem(prev.system, delta.system) : prev.system const tools = delta.tools !== undefined ? applyTools(prev.tools ?? [], delta.tools) : prev.tools const messagePrefix = delta.messagePrefix ?? prev.messagePrefix - const messageSuffix = delta.messageSuffix ?? prev.messageSuffix return canonicalHeader({ config: delta.config ?? prev.config, ...system !== undefined ? { system } : {}, ...tools !== undefined ? { tools } : {}, ...messagePrefix !== undefined ? { messagePrefix } : {}, - ...messageSuffix !== undefined ? { messageSuffix } : {}, }) } diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index 75fc84d9a0..ca6779e1dc 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -185,14 +185,13 @@ export interface TodoItem { /** * The request header: everything about an LLM request besides its derived * message history — the call configuration plus the rendered system prompt, - * tool schemas, and any request-only messages. Logged session state (the + * tool schemas, and the session prefix. Logged session state (the * reconstructability RFC): a * {@link SessionEventMap} `request/header` snapshot installs one, a * `request/header-delta` amends it, and folding those events over the log * (`foldRequestHeader`) reconstructs the header any request was built under. - * Canonical form: an empty system prompt, an empty tool list, and empty - * request-only message arrays are ABSENT fields, matching how requests are - * built. + * Canonical form: an empty system prompt, an empty tool list, and an empty + * prefix are ABSENT fields, matching how requests are built. */ export interface EpochHeader { /** The conversation's call configuration (model + sampling scalars). */ @@ -202,14 +201,13 @@ export interface EpochHeader { /** Assembled tool schemas; absent for a tool-less request. */ tools?: ToolSchema[] /** - * Request-only messages sent BEFORE the derived history (the - * `agent/request-advice` waterfall's `before` contributions). Not session - * history — `deriveMessages()` never returns them — so the header is their - * only durable record; absent when the request carried none. + * The session prefix: request-only messages sent BEFORE the entire derived + * history (the `agent/session-prefix` waterfall's product, composed once + * per loop instance and reused for every request it sends). Not session + * history — `deriveMessages()` never returns it — so the header is its + * only durable record; absent when the instance composed none. */ messagePrefix?: Message[] - /** Request-only messages sent AFTER the derived history; absent when none. */ - messageSuffix?: Message[] } /** @@ -369,9 +367,11 @@ export interface SessionEventMap { * Amendment to the folded {@link EpochHeader}: at least one of a * {@link SystemDelta}, a {@link ToolsDelta}, a whole replacement * {@link LlmCallConfig} (four scalars — not worth diffing), or a whole - * replacement request-only message array (`messagePrefix`/`messageSuffix` — - * small advisory content, replaced whole; an EMPTY array encodes the - * transition to "none", mirroring the canonical form's absent field). + * replacement session prefix (`messagePrefix` — small advisory content, + * replaced whole; an EMPTY array encodes the transition to "none", + * mirroring the canonical form's absent field — the loop never produces + * one in practice: the prefix is composed once per instance and anchored + * by that instance's snapshot, so this arm exists for codec totality). * Appended by the * loop inside the step, before dispatch, when the header for this request * differs from the fold of the log so far; the writer verifies @@ -379,7 +379,7 @@ export interface SessionEventMap { * falls back to a `'fallback'` `request/header` snapshot when it cannot, so * a logged delta ALWAYS round-trips. NOT a {@link SurfaceEventType}. */ - 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[]; messageSuffix?: Message[] } + 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } } /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */ diff --git a/packages/core/session/tests/request-header.spec.ts b/packages/core/session/tests/request-header.spec.ts index 9db46598ac..8a5af819c3 100644 --- a/packages/core/session/tests/request-header.spec.ts +++ b/packages/core/session/tests/request-header.spec.ts @@ -107,38 +107,37 @@ describe('diffHeader / applyHeaderDelta', () => { }) }) -describe('request-only messages (messagePrefix / messageSuffix)', () => { - it('canonicalHeader normalizes empty arrays to absent fields', () => { - expect(canonicalHeader({ config: CONFIG, messagePrefix: [], messageSuffix: [] })).toEqual({ config: CONFIG }) - const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')], messageSuffix: [msg('s')] }) +describe('the session prefix (messagePrefix)', () => { + it('canonicalHeader normalizes an empty prefix to an absent field', () => { + expect(canonicalHeader({ config: CONFIG, messagePrefix: [] })).toEqual({ config: CONFIG }) + const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] }) expect(full.messagePrefix).toEqual([msg('p')]) - expect(full.messageSuffix).toEqual([msg('s')]) }) it('headerEquals treats absence and empty as one representation, content differences as unequal', () => { expect(headerEquals(canonicalHeader({ config: CONFIG }), { config: CONFIG, messagePrefix: [] })).toBe(true) expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG, messagePrefix: [msg('b')] })).toBe(false) - expect(headerEquals({ config: CONFIG, messageSuffix: [msg('a')] }, { config: CONFIG })).toBe(false) + expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG })).toBe(false) }) - it('replaces a changed prefix whole and leaves an untouched suffix alone', () => { - const prev = canonicalHeader({ config: CONFIG, messagePrefix: [msg('old')], messageSuffix: [msg('keep')] }) - const next = canonicalHeader({ config: CONFIG, messagePrefix: [msg('new'), msg('more')], messageSuffix: [msg('keep')] }) + it('replaces a changed prefix whole and leaves untouched parts alone', () => { + const prev = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('old')] }) + const next = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('new'), msg('more')] }) const delta = roundTrip(prev, next) expect(delta).toEqual({ messagePrefix: [msg('new'), msg('more')] }) }) - it('round-trips framing gained from a bare header and lost back to one (empty array encodes absence)', () => { + it('round-trips a prefix gained from a bare header and lost back to one (empty array encodes absence)', () => { const none = canonicalHeader({ config: CONFIG }) - const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')], messageSuffix: [msg('s')] }) + const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] }) const gained = roundTrip(none, some) - expect(gained).toEqual({ messagePrefix: [msg('p')], messageSuffix: [msg('s')] }) + expect(gained).toEqual({ messagePrefix: [msg('p')] }) const lost = roundTrip(some, none) - expect(lost).toEqual({ messagePrefix: [], messageSuffix: [] }) + expect(lost).toEqual({ messagePrefix: [] }) }) - it('folds framing deltas over the log like any other header amendment', () => { - const session = new Session(SessionId('fold-framing')) + it('folds prefix deltas over the log like any other header amendment', () => { + const session = new Session(SessionId('fold-prefix')) session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) const first = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v1')] }) session.append('request/header', { header: first, reason: 'initial' }) diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts index 48125fff0d..e3339869a5 100644 --- a/packages/llm/llm/src/types.ts +++ b/packages/llm/llm/src/types.ts @@ -175,8 +175,8 @@ export interface GenerateOptions { /** * Ordered conversation messages, exactly as the provider sees them (after * the `system` slot). A loop-built request assembles them as - * `EpochHeader.messagePrefix` + the derived history + `messageSuffix` - * (dsh-agent-loop); a hand-built one-shot passes any list. + * `EpochHeader.messagePrefix` + the derived history (dsh-agent-loop); a + * hand-built one-shot passes any list. */ messages: Message[] /** System prompt text (adapters map to the provider's system slot). */ diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts index 216049da09..8147a6deb6 100644 --- a/packages/support/invariants/src/index.ts +++ b/packages/support/invariants/src/index.ts @@ -367,9 +367,9 @@ export function apply(ctx: Context, config: Config = {}): void { // hand-built one-shot (compaction summarize) is unfrozen and skipped — must // be EXACTLY what the session log reconstructs: // - // - messages: the folded header's request-only messages (messagePrefix / - // messageSuffix — the `agent/request-advice` contributions, logged on - // the header because no session event carries them) framing the + // - messages: the folded header's session prefix (messagePrefix — the + // `agent/session-prefix` product, logged on the header because no + // session event carries it) followed by the // derivation over the log prefix strictly before the in-flight step's // `step/start` (the reconstruction boundary). The derivation is compared // against a FRESH Session built over that prefix — the same projection @@ -416,13 +416,13 @@ export function apply(ctx: Context, config: Config = {}): void { throw new InvariantError('a loop-built request with no request/header event in its session log') } const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary))) - // The reconstruction equation: the folded header's request-only messages - // frame the boundary derivation (prefix + derived + suffix) — the loop + // The reconstruction equation: the folded header's session prefix, then + // the boundary derivation — the loop // logs the header event BEFORE dispatch, so the fold already covers this - // request's contributions. JSON equality is sound here: both sides are + // request's prefix. JSON equality is sound here: both sides are // structuredClones produced by the same projection/build code path, so key // insertion order matches when the values do. - const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages(), ...header.messageSuffix ?? []] + const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()] if (JSON.stringify(options.messages) !== JSON.stringify(expected)) { throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`) } diff --git a/packages/support/invariants/tests/invariants.spec.ts b/packages/support/invariants/tests/invariants.spec.ts index cccd6a54d4..af31f01911 100644 --- a/packages/support/invariants/tests/invariants.spec.ts +++ b/packages/support/invariants/tests/invariants.spec.ts @@ -707,19 +707,18 @@ describe('request-reconstruction cross-check (llm/stream)', () => { expect(() => { dispatch(ctx, options) }).not.toThrow() }) - it('expects the folded header\'s request-only messages to frame the derivation (prefix + derived + suffix)', async () => { + it('expects the folded header\'s session prefix ahead of the derivation (prefix + derived)', async () => { const { ctx, session, boundary } = await requestSetup() const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: 'catalog' }] } - const suffix = { role: 'user' as const, content: [{ type: 'text' as const, text: 'trailing note' }] } - session.append('request/header-delta', { messagePrefix: [prefix], messageSuffix: [suffix] }) - // The framed request matches the fold… - const framed = Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary, suffix]), sessionId: session.id }) - expect(() => { dispatch(ctx, framed) }).not.toThrow() - // …a request that DROPPED the logged framing diverges… + session.append('request/header-delta', { messagePrefix: [prefix] }) + // The prefixed request matches the fold… + const prefixed = Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id }) + expect(() => { dispatch(ctx, prefixed) }).not.toThrow() + // …a request that DROPPED the logged prefix diverges… const bare = Object.freeze({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id }) expect(() => { dispatch(ctx, bare) }).toThrow(/diverges from the boundary derivation/) - // …and so does one that misplaced it (suffix sent as a prefix). - const misplaced = Object.freeze({ model: 'm', messages: Object.freeze([suffix, prefix, ...boundary]), sessionId: session.id }) + // …and so does one that misplaced it (prefix sent after the history). + const misplaced = Object.freeze({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id }) expect(() => { dispatch(ctx, misplaced) }).toThrow(/diverges from the boundary derivation/) }) diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index dfa3be16c4..b66882d8c9 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -15,8 +15,6 @@ { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "RequestAdvice", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "RequestAdviceContext", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" }, { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" }, From a83eb5d5c2e6976d389180ea9a47a07b67fc75a7 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 8 Jul 2026 15:46:46 +0800 Subject: [PATCH 056/119] docs: fit packages/README budget after merging code-runtime + timeout rows The master merge added a code-runtime/ package row while this branch adds the timeout/ row; together they push packages/README.md over its 605-word ceiling. Condense the timeout/ row to the terse sibling style and raise the ceiling 605->610 for the genuinely-new package group, mirroring how the code-runtime work raised architecture.md's ceiling in the same spirit. --- packages/README.md | 2 +- scripts/doc-budgets.manifest.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/README.md b/packages/README.md index eb73457204..0c39434e40 100644 --- a/packages/README.md +++ b/packages/README.md @@ -16,7 +16,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface | -| [`timeout/`](timeout/README.md) | Tool-call timeout policy: a `tools/execute` wrapper arming a per-tool deadline on `exec.signal` | Product — stable surface | +| [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index fc2b9d12c2..337fc57763 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -7,5 +7,5 @@ "docs/testing.md": 800, "examples/AGENTS.md": 610, "packages/AGENTS.md": 450, - "packages/README.md": 605 + "packages/README.md": 610 } From 77333c0a19c034890b4197deedc9fd15f2c75d54 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 16:16:08 +0800 Subject: [PATCH 057/119] fix(agent): correct session-prefix composition-order docs; scrub messagePrefix in snapshots MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two ds-review-bot findings: The seam JSDoc claimed extending 'await next()' composes in registration order — false for the append form: the waterfall unwinds innermost-first, so appending places later-registered contributions first. The canonical contribution is now documented as the PREPEND '[mine, ...await next()]' (registration order on the wire), with the append form's reverse-order behavior stated explicitly; the ordering test now uses the canonical pattern in both listeners. scrubRequestHeaders tokenized only system/tools, so a fixture recording a composed session prefix would carry its raw text (workspace-specific churn/leak). The scrubber now maps each header/delta messagePrefix entry to a {{messagePrefix}} token — count stays a structural fact, absence stays absent, the empty-array transition stays visible — with normalize.spec coverage for the header, delta, absence, and odd-shape paths. --- docs/cordis-catalog/events.md | 10 +++--- docs/event-producer-consumer.md | 8 ++--- .../agent-loop/tests/interception.spec.ts | 9 +++--- packages/core/agent/src/types.ts | 11 +++++-- .../support/acp-snapshot/src/normalize.ts | 30 ++++++++++++----- .../acp-snapshot/tests/normalize.spec.ts | 32 +++++++++++++++++++ 6 files changed, 76 insertions(+), 24 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 20cd367f32..e9b213c2fa 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -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:455`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:460`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -105,7 +105,7 @@ Waterfall: compose the SESSION PREFIX — request-only messages placed in front This is the home for session-stable openers the model must always see but that must NOT become durable history — a skills catalog, an AGENTS.md digest, a workspace baseline: `Session.deriveMessages()` never returns the prefix, and the header events are its only durable record, so the request stays reconstructable from the log. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, a `tools/post-execute` decision's `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter. -The seed is a frozen empty list; a contributing listener returns a NEW array extending `await next()` (`[...prefix, mine]` — never an in-place push), so contributions compose across plugins in registration order and compose deterministically for a fixed plugin set. Call `next()` to delegate, or return a list without it to short-circuit. +The seed is a frozen empty list; a contributing listener returns a NEW array — never an in-place push. The canonical contribution is a PREPEND, `[mine, ...await next()]`: the waterfall unwinds innermost-first (the LAST-registered listener's `next()` resolves first), so prepending yields registration order on the wire, and every plugin using it composes deterministically. The append form `[...await next(), mine]` is legal but places a contribution AFTER every later-registered plugin's — reverse registration order when all contributors append. Call `next()` to delegate, or return a list without it to short-circuit. ```ts cordis-catalog 'agent/session-prefix'(agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise): Promise @@ -113,7 +113,7 @@ The seed is a frozen empty list; a contributing listener returns a NEW array ext Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:425`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -149,7 +149,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:430`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:435`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -161,7 +161,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:443`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:448`](../../packages/core/agent/src/types.ts) ## `fs/*` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 834dfc6d69..534a0af269 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -9,16 +9,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac | --- | --- | --- | --- | --- | | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:455`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:460`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:350`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | | `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:363`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:290`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:387`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:425`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:305`](../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:281`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:430`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:443`](../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/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:435`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:448`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../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:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index c3f301afc7..d97710e6d6 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -352,23 +352,24 @@ describe('agent/session-prefix', () => { expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] }) }) - it('contributions compose across listeners in registration order', async () => { + it('the canonical prepend pattern composes contributions in registration order', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + // Both listeners use the canonical `[mine, ...await next()]` prepend: the + // waterfall unwinds innermost-first (the second listener's array is built + // first), so prepending puts the FIRST-registered contribution first. ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { return [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...await next()] }) ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { - return [...await next(), { role: 'user', content: [{ type: 'text', text: 'second' }] }] + return [{ role: 'user', content: [{ type: 'text', text: 'second' }] }, ...await next()] }) send(agent, 'hi') await waitForIdle(ctx, agent) - // Registration order composes: the first listener runs last on the way - // out (waterfall), so its prepend lands first. const texts = adapter.requests[0]!.messages.map(m => m.content[0]?.type === 'text' ? m.content[0].text : '') expect(texts).toEqual(['first', 'second', 'hi']) }) diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 27af421b17..9121fe87bb 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -408,9 +408,14 @@ declare module 'cordis' { * durable `context/message` paid once and prefix-cached thereafter. * * The seed is a frozen empty list; a contributing listener returns a NEW - * array extending `await next()` (`[...prefix, mine]` — never an in-place - * push), so contributions compose across plugins in registration order - * and compose deterministically for a fixed plugin set. Call `next()` to + * array — never an in-place push. The canonical contribution is a + * PREPEND, `[mine, ...await next()]`: the waterfall unwinds + * innermost-first (the LAST-registered listener's `next()` resolves + * first), so prepending yields registration order on the wire, and every + * plugin using it composes deterministically. The append form + * `[...await next(), mine]` is legal but places a contribution AFTER + * every later-registered plugin's — reverse registration order when all + * contributors append. Call `next()` to * delegate, or return a list without it to short-circuit. * @param agent - the agent whose session prefix is being composed. * @param prefix - the frozen empty seed; return an extended replacement to contribute. diff --git a/packages/support/acp-snapshot/src/normalize.ts b/packages/support/acp-snapshot/src/normalize.ts index 2cbe914b42..017dd504b3 100644 --- a/packages/support/acp-snapshot/src/normalize.ts +++ b/packages/support/acp-snapshot/src/normalize.ts @@ -13,8 +13,9 @@ * (deterministic — `seq = log.length`, part of the event-log contract). * * A separate, composable normalizer — {@link scrubRequestHeaders} — replaces - * the bulky request-header CONTENT (the composed system prompt and the tool - * schema list) with `{{system}}`/`{{tools}}` tokens. It is deliberately NOT + * the bulky request-header CONTENT (the composed system prompt, the tool + * schema list, and the session prefix) with + * `{{system}}`/`{{tools}}`/`{{messagePrefix}}` tokens. It is deliberately NOT * folded into {@link normalizeSessionLog}: each suite's one header-pinning * scenario compares that content verbatim, every other scenario composes the * scrub in (the `pinsHeader` flag on the scenario table, consumed by the suite @@ -30,6 +31,7 @@ const SESSION_ID = '{{sessionId}}' const CWD = '{{cwd}}' const SYSTEM = '{{system}}' const TOOLS = '{{tools}}' +const MESSAGE_PREFIX = '{{messagePrefix}}' /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */ const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi @@ -135,15 +137,22 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri /** * Replace request-header CONTENT in a session JSONL with stable tokens, * keeping its structure: a `request/header` event's `data.header.system` → - * `{{system}}` and `data.header.tools` → `{{tools}}`; a + * `{{system}}`, `data.header.tools` → `{{tools}}`, and + * `data.header.messagePrefix` → one `{{messagePrefix}}` token per message + * (the session prefix is model-visible bulk — an AGENTS digest, a skills + * catalog — so its COUNT stays a structural fact while its text never lands + * in a fixture); a * `request/header-delta` event keeps every structural fact — the system * delta's `keepStart`/`keepEnd` line positions and inserted-line COUNT (one * `{{system}}` token per inserted line), the tools delta's - * added/removed/changed tool NAMES — and tokenizes only the bulk (prompt - * text; each added/changed schema's fields other than `name` → `{{tools}}`), + * added/removed/changed tool NAMES, the prefix replacement's message COUNT — + * and tokenizes only the bulk (prompt + * text; each added/changed schema's fields other than `name` → `{{tools}}`; + * each replacement prefix message → `{{messagePrefix}}`), * so two different deltas still compare different. - * Absent fields stay absent — WHETHER a header carried a system prompt or - * tools is behavior and stays visible; `config` and `reason` are small and + * Absent fields stay absent — WHETHER a header carried a system prompt, + * tools, or a prefix is behavior and stays visible; `config` and `reason` + * are small and * stable, so they stay verbatim (a model swap churns every fixture by design * — it invalidates the recorded responses; a prompt/schema edit churns none — * replay never reads this content, see dsh-llm-replay). @@ -166,9 +175,10 @@ export function scrubRequestHeaders(rawLog: string): string { if (record.type === 'request/header') { const header = data.header as Record | null | undefined if (header === null || typeof header !== 'object') return line - if (!('system' in header) && !('tools' in header)) return line + if (!('system' in header) && !('tools' in header) && !('messagePrefix' in header)) return line if ('system' in header) header.system = SYSTEM if ('tools' in header) header.tools = TOOLS + if (Array.isArray(header.messagePrefix)) header.messagePrefix = header.messagePrefix.map(() => MESSAGE_PREFIX) return JSON.stringify(record) } if (record.type === 'request/header-delta') { @@ -183,6 +193,10 @@ export function scrubRequestHeaders(rawLog: string): string { if (Array.isArray(tools.added)) { tools.added = tools.added.map(scrubToolSchema); touched = true } if (Array.isArray(tools.changed)) { tools.changed = tools.changed.map(scrubToolSchema); touched = true } } + if (Array.isArray(data.messagePrefix)) { + data.messagePrefix = data.messagePrefix.map(() => MESSAGE_PREFIX) + touched = true + } return touched ? JSON.stringify(record) : line } return line diff --git a/packages/support/acp-snapshot/tests/normalize.spec.ts b/packages/support/acp-snapshot/tests/normalize.spec.ts index 8ebd1412b9..daa9f8342d 100644 --- a/packages/support/acp-snapshot/tests/normalize.spec.ts +++ b/packages/support/acp-snapshot/tests/normalize.spec.ts @@ -155,6 +155,38 @@ describe('scrubRequestHeaders', () => { expect(toolsOnly).not.toContain('{{system}}') }) + it('scrubs the header session prefix to one token per message, keeping the count', () => { + const ev = headerEvent({ + config: { model: 'm' }, + messagePrefix: [ + { role: 'user', content: [{ type: 'text', text: 'workspace AGENTS digest' }] }, + { role: 'user', content: [{ type: 'text', text: 'skills catalog' }] }, + ], + }) + const out = scrubRequestHeaders(`${headerLine}\n${ev}\n`) + expect(out).toContain('"messagePrefix":["{{messagePrefix}}","{{messagePrefix}}"]') + expect(out).not.toContain('AGENTS digest') + expect(out).not.toContain('skills catalog') + // Absence stays absent — a prefix-less header gains no token… + expect(scrubRequestHeaders(`${headerLine}\n${headerEvent({ system: 's' })}\n`)).not.toContain('{{messagePrefix}}') + // …and a non-array shape passes through untouched. + const odd = JSON.stringify({ type: 'request/header', seq: 4, time: 9, data: { header: { config: { model: 'm' }, messagePrefix: 'weird' }, reason: 'initial' } }) + expect(scrubRequestHeaders(`${headerLine}\n${odd}\n`)).toContain('"messagePrefix":"weird"') + }) + + it('scrubs a header-delta prefix replacement to one token per message', () => { + const delta = JSON.stringify({ + type: 'request/header-delta', seq: 8, time: 9, + data: { messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'leaked opener' }] }] }, + }) + const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`) + expect(out).toContain('"messagePrefix":["{{messagePrefix}}"]') + expect(out).not.toContain('leaked opener') + // The empty-array transition-to-absence stays a structural fact. + const toNone = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { messagePrefix: [] } }) + expect(scrubRequestHeaders(`${headerLine}\n${toNone}\n`)).toContain('"messagePrefix":[]') + }) + it('leaves a delta with no scrubbable payload byte-identical (config-only, or non-array shapes)', () => { const configOnly = JSON.stringify({ type: 'request/header-delta', seq: 8, time: 9, data: { config: { model: 'm2' } } }) const oddShapes = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { system: { insert: 'not-an-array' }, tools: null } }) From cdd1ce2ad4ab5851de949f13ba085b306b8e70b2 Mon Sep 17 00:00:00 2001 From: pku-xht Date: Wed, 8 Jul 2026 15:31:14 +0800 Subject: [PATCH 058/119] feat(subagent): extract dsh-subagent-process shared out-of-process machinery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The credential env scrub (SENSITIVE_ENV_PATTERN/buildChildEnv), the spawn-failure capture (spawnFailure), the child-exit waits (waitForExit/exitsWithin), and the stdin-EOF -> SIGTERM -> SIGKILL dispose ladder move out of subagent-acp into a new pure library package (the subagent-inprocess shape), with the ladder taking its two grace periods as parameters — defaults stay in the plugin Config. New isolated-config-dir helpers (mkdtemp create, best-effort remove; a pinned dir is never removed) land alongside for the CLAUDE_CONFIG_DIR / CODEX_HOME redirection the RFC names. The ACP backend migrates onto the library with no semantic change: its suite passes with import-path edits only. bash-local keeps its sibling copy, per the RFC's blast-radius call. RFC: docs/rfc/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md --- docs/config-catalog.md | 1 + docs/module-graph.md | 5 +- knip.json | 5 + packages/subagent/README.md | 3 +- packages/subagent/subagent-acp/package.json | 2 + packages/subagent/subagent-acp/src/run.ts | 98 ++---- .../subagent-acp/tests/subagent-acp.spec.ts | 3 +- packages/subagent/subagent-acp/tsconfig.json | 3 + packages/subagent/subagent-process/README.md | 40 +++ .../subagent/subagent-process/package.json | 30 ++ .../subagent/subagent-process/src/index.ts | 207 ++++++++++++ .../tests/subagent-process.spec.ts | 307 ++++++++++++++++++ .../subagent/subagent-process/tsconfig.json | 11 + pnpm-lock.yaml | 9 + tsconfig.build.json | 1 + tsconfig.json | 1 + 16 files changed, 645 insertions(+), 81 deletions(-) create mode 100644 packages/subagent/subagent-process/README.md create mode 100644 packages/subagent/subagent-process/package.json create mode 100644 packages/subagent/subagent-process/src/index.ts create mode 100644 packages/subagent/subagent-process/tests/subagent-process.spec.ts create mode 100644 packages/subagent/subagent-process/tsconfig.json diff --git a/docs/config-catalog.md b/docs/config-catalog.md index e55066101f..c01d42f87d 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -816,3 +816,4 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them. - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts)) - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)) - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts)) +- `@deepseek-ai/dsh-subagent-process` ([`packages/subagent/subagent-process/src/index.ts`](../packages/subagent/subagent-process/src/index.ts)) diff --git a/docs/module-graph.md b/docs/module-graph.md index 5e043d22d4..cadf8d0d14 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -43,6 +43,7 @@ flowchart TD pkg_subagent_acp["subagent-acp"] pkg_subagent_fork["subagent-fork"] pkg_subagent_inprocess["subagent-inprocess"] + pkg_subagent_process["subagent-process"] pkg_subagent_spawn["subagent-spawn"] pkg_tool_subagent["tool-subagent"] end @@ -171,6 +172,7 @@ flowchart TD pkg_subagent_acp --> pkg_agent pkg_subagent_acp --> pkg_llm pkg_subagent_acp --> pkg_subagent + pkg_subagent_acp --> pkg_subagent_process pkg_subagent_inprocess --> pkg_agent pkg_subagent_inprocess --> pkg_llm pkg_subagent_inprocess --> pkg_session @@ -211,6 +213,7 @@ flowchart TD | Package | Group | Depends on | | --- | --- | --- | | [`brand`](../packages/util/brand) | `util` | — | +| [`subagent-process`](../packages/subagent/subagent-process) | `subagent` | — | | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — | | [`app-boot`](../packages/ui/app-boot) | `ui` | — | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — | @@ -248,7 +251,7 @@ flowchart TD | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) | -| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | +| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-process`](../packages/subagent/subagent-process) | | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | diff --git a/knip.json b/knip.json index 8c0f71f3af..1ab6d39a9e 100644 --- a/knip.json +++ b/knip.json @@ -66,6 +66,11 @@ "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/mock-acp-server.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, + "packages/subagent/subagent-process": { + "entry": ["tests/**/*.spec.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"], + "ignoreDependencies": ["cordis"] + }, "packages/fs/tool-fs": { "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] diff --git a/packages/subagent/README.md b/packages/subagent/README.md index 6da8ee42f5..38c64d22a5 100644 --- a/packages/subagent/README.md +++ b/packages/subagent/README.md @@ -8,9 +8,10 @@ The subagent seam: an agent delegating work to a child agent. Like the [bash](.. | `subagent-inprocess/` | Shared in-process run driver (pure lib; registers nothing) | — | | `subagent-spawn/` | In-process backend: a fresh child agent | (registers on `ctx.subagents`) | | `subagent-fork/` | In-process backend: a child seeded with the parent's completed-turn prefix | (registers on `ctx.subagents`) | +| `subagent-process/` | Shared out-of-process machinery: env scrub, dispose ladder, isolated config dirs (pure lib; registers nothing) | — | | `subagent-acp/` | Out-of-process backend: a child agent in a spawned subprocess, driven over ACP | (registers on `ctx.subagents`) | | `tool-subagent/` | Model-facing `subagent` delegation tool over `ctx.subagents` | (registers on `ctx.tools`) | -The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a pure library — both depend on it, neither on the other), and the out-of-process `subagent-acp` backend ships alongside them here; the test-only `dsh-subagent-mock` (in [support](../support/README.md)) is separate. All **product** packages except the mock. +The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a pure library — both depend on it, neither on the other), the out-of-process `subagent-acp` backend builds on the `subagent-process` library (the credential env scrub, the dispose ladder, isolated config dirs) and ships alongside them here; the test-only `dsh-subagent-mock` (in [support](../support/README.md)) is separate. All **product** packages except the mock. The proposal and design rationale: [docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md](../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md). diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json index 2c55051da9..45fc6b072c 100644 --- a/packages/subagent/subagent-acp/package.json +++ b/packages/subagent/subagent-acp/package.json @@ -25,6 +25,7 @@ "@deepseek-ai/dsh-agent": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-subagent": "^0.0.1", + "@deepseek-ai/dsh-subagent-process": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "dependencies": { @@ -35,6 +36,7 @@ "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", + "@deepseek-ai/dsh-subagent-process": "workspace:^", "@cordisjs/plugin-loader": "^1.0.0-rc.4", "cordis": "^4.0.0-rc.6" } diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts index d7631f4d8d..a94c923f46 100644 --- a/packages/subagent/subagent-acp/src/run.ts +++ b/packages/subagent/subagent-acp/src/run.ts @@ -22,7 +22,7 @@ * @module @deepseek-ai/dsh-subagent-acp/run */ -import { spawn, type ChildProcess } from 'node:child_process' +import { spawn } from 'node:child_process' import { randomUUID } from 'node:crypto' import { Readable, Writable } from 'node:stream' import { @@ -40,6 +40,7 @@ import { import { AgentId } from '@deepseek-ai/dsh-agent' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent' +import { buildChildEnv, disposeChildProcess, spawnFailure } from '@deepseek-ai/dsh-subagent-process' /** * How the client answers a child's `session/request_permission`. The first cut @@ -110,31 +111,6 @@ export const DEFAULT_DISPOSE_EOF_GRACE_MS = 6_000 /** Default grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config; mirrors the bash executor). */ export const DEFAULT_DISPOSE_GRACE_MS = 3_000 -/** - * Credential-shaped ambient env vars are NOT forwarded to the child by default - * (the parent harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a - * spawned process implicitly). Same pattern as the bash executor. The child - * agent needs its OWN credentials to reach a model — those are supplied - * explicitly via {@link AcpRunSpec.env}, which is layered on top AFTER the - * scrub, so an intended `DEEPSEEK_API_KEY` survives while an incidental - * `AWS_SECRET_ACCESS_KEY` does not. - */ -export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i - -/** - * The ambient env minus credential-shaped vars, plus the spec's explicit env. - * @param extra - explicit vars layered on top AFTER the scrub, so a - * credential-shaped name supplied deliberately still reaches the child. - * @returns the environment to spawn the child with. - */ -export function buildChildEnv(extra: Record): NodeJS.ProcessEnv { - const env: NodeJS.ProcessEnv = {} - for (const [key, value] of Object.entries(process.env)) { - if (!SENSITIVE_ENV_PATTERN.test(key)) env[key] = value - } - return { ...env, ...extra } -} - /** * Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}. * @param reason - the terminal reason from the child's `session/prompt` response. @@ -196,24 +172,6 @@ function toError(value: unknown): Error { return value instanceof Error ? value : new Error(String(value)) } -/** Resolve once the child process exits (any code/signal); immediate if gone. */ -function waitForExit(child: ChildProcess): Promise { - // Already-exited fast path: dispose guards on exitCode before calling, so in - // tests the child is always still alive here. - /* v8 ignore next */ - if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve() - return new Promise(resolve => child.once('exit', () => { resolve() })) -} - -/** Resolve `true` if the child exits within `ms`, `false` on timeout. */ -function exitsWithin(child: ChildProcess, ms: number): Promise { - return Promise.race([ - waitForExit(child).then(() => true), - // `.unref()` so a pending grace timer never keeps the parent's loop alive. - new Promise(resolve => setTimeout(() => { resolve(false) }, ms).unref()), - ]) -} - /** * Start an out-of-process ACP child for `request` and return a {@link SubagentRun}. * @@ -254,13 +212,11 @@ export function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): Su env: buildChildEnv(spec.env), stdio: ['pipe', 'pipe', 'inherit'], }) - // A spawn-level failure (e.g. ENOENT for a bad command) is emitted as an - // `error` event, NOT a thrown exception — without a listener Node treats it as - // an unhandled error and crashes the parent. Capture it into a promise the - // result path races, so a bad command settles `error` like any child failure. - const spawnFailed = new Promise((resolve) => { - child.once('error', (err) => { resolve(err) }) - }) + // Same-tick capture (the library's contract): a spawn-level failure (e.g. + // ENOENT for a bad command) is an `error` EVENT that would crash the parent + // unheard; the result path races this promise, so a bad command settles + // `error` like any child failure. + const spawnFailed = spawnFailure(child) // Accumulate the child's streamed assistant text — the SubagentResult output. const output: string[] = [] @@ -393,33 +349,19 @@ export function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): Su }, async dispose(): Promise { request.signal?.removeEventListener('abort', onAbort) - // Reach quiescence, not merely request it (dispose must AWAIT the child - // actually stopping). If the child is already gone, nothing to do. - if (child.exitCode !== null || child.signalCode !== null) return - const eofGraceMs = spec.disposeEofGraceMs - const graceMs = spec.disposeGraceMs - // 1. Graceful: end the ACP request stream (stdin EOF) and let the child - // quiesce ON ITS OWN. Our acp-agent has NO SIGTERM handler in a normal - // session — it tears down via the server bridge's connection-close path - // (conn.closed → per-agent dispose → final session/flush), driven by the - // stdin EOF, NOT by a signal. A prompt response can resolve from a - // turn/end BEFORE that post-turn flush lands, so the child still has - // durable work owed when dispose runs. Give the EOF-driven quiesce a real - // window — wider than a single signal-grace, since the child's own - // teardown may itself be awaiting a signal-trapping grandchild (a bash - // subprocess in its own SIGTERM→SIGKILL grace) plus a flush — and only - // escalate if it overruns. Sending SIGTERM in the same tick (or too soon) - // would default-terminate the child mid-flush, orphaning its nested work. - child.stdin.end() - if (await exitsWithin(child, eofGraceMs)) return - // 2. SIGTERM, then escalate to SIGKILL if it still does not exit within the - // grace period — a child that ignores EOF and traps SIGTERM must not - // wedge dispose forever (the seam requires bounded quiescence). - child.kill('SIGTERM') - if (await exitsWithin(child, graceMs)) return - // 3. Force-kill and await the (now-certain) exit. - child.kill('SIGKILL') - await waitForExit(child) + // Quiescent teardown via the shared ladder (stdin EOF → SIGTERM → + // SIGKILL, awaiting the actual exit). For THIS child the EOF tier is the + // one that matters: our acp-agent has NO SIGTERM handler in a normal + // session — it tears down via the server bridge's connection-close path + // (conn.closed → per-agent dispose → final session/flush), driven by the + // stdin EOF, NOT by a signal — and a prompt response can resolve from a + // turn/end BEFORE that post-turn flush lands, so the child still has + // durable work owed when dispose runs (hence the wide EOF grace; see + // DEFAULT_DISPOSE_EOF_GRACE_MS). + await disposeChildProcess(child, { + disposeEofGraceMs: spec.disposeEofGraceMs, + disposeGraceMs: spec.disposeGraceMs, + }) }, } } diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index 3eb12fac38..6d351c71d0 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -6,9 +6,10 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' import SubagentService from '@deepseek-ai/dsh-subagent' +import { buildChildEnv, SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subagent-process' import type { Agent } from '@deepseek-ai/dsh-agent' import * as acp from '../src/index.ts' -import { acpStopReason, acpContentText, buildChildEnv, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, SENSITIVE_ENV_PATTERN, startAcpRun, toAcpPrompt, type AcpRunSpec } from '../src/run.ts' +import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, startAcpRun, toAcpPrompt, type AcpRunSpec } from '../src/run.ts' /** * Keyless integration tests for the ACP subagent backend. Each spawns a REAL diff --git a/packages/subagent/subagent-acp/tsconfig.json b/packages/subagent/subagent-acp/tsconfig.json index 3c06fef150..ab24f60f93 100644 --- a/packages/subagent/subagent-acp/tsconfig.json +++ b/packages/subagent/subagent-acp/tsconfig.json @@ -25,6 +25,9 @@ }, { "path": "../subagent" + }, + { + "path": "../subagent-process" } ] } diff --git a/packages/subagent/subagent-process/README.md b/packages/subagent/subagent-process/README.md new file mode 100644 index 0000000000..597470f52a --- /dev/null +++ b/packages/subagent/subagent-process/README.md @@ -0,0 +1,40 @@ +# @deepseek-ai/dsh-subagent-process + +Shared machinery for **out-of-process subagent backends** — providers that spawn an external agent as a child process, such as the [ACP backend](../subagent-acp/README.md). A pure library (no provider, no registration, no Config): what every spawn-a-CLI-child backend needs to keep the parent deployment's credentials out of the child, tear the child down to quiescence, and isolate it from the host user's on-disk CLI state. Design rationale: [the Claude Code / Codex subagent backends RFC](../../../docs/rfc/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md). + +Every tunable is a **parameter**: the dispose ladder takes its grace periods per call, the config-dir helper takes an optional pinned path. Defaults live in each consuming plugin's Config (defaulted, validated fields changeable from `cordis.yml`), never in this library. + +## What it exports + +### `SENSITIVE_ENV_PATTERN` / `buildChildEnv(extra)` + +The credential env scrub (same pattern as the [bash executor](../../bash/bash-local/README.md)): the child env is the ambient env minus credential-shaped vars (`/KEY|SECRET|TOKEN/i`), with `extra` layered on top AFTER the scrub. `PATH`, `HOME`, `TMPDIR`, locale, and proxy vars survive, so the child CLI runs normally; the parent's own secrets never leak implicitly, while an explicitly supplied credential (the child's OWN key in a backend's `env` config) still reaches the child. + +### `spawnFailure(child)` + +Spawn-failure capture: a promise that resolves (never rejects) with the child's first `error` event. A spawn failure such as `ENOENT` is an event, not a thrown exception — without a listener Node crashes the parent process — so call this in the same tick as `spawn()` and race it in the run's result path; a bad command then settles as an ordinary child-level failure. For a child that spawns cleanly the promise never settles. + +### `waitForExit(child)` / `exitsWithin(child, ms)` + +Exit waits over a `ChildProcess`: resolve once the child exits by any code or signal (immediately if it is already gone), or race that against a timer (`true` = exited in time; the pending timer is `unref()`ed so a grace window never keeps the parent's event loop alive). + +### `disposeChildProcess(child, graces)` + +The three-tier dispose ladder. Resolves only once the child has ACTUALLY exited — quiescence reached, not merely requested (see [defensive patterns](../../../docs/defensive-patterns.md)): + +1. stdin EOF (when stdin is piped), then wait `graces.disposeEofGraceMs` — a cooperative child quiesces on its own, its flushes and nested-subprocess teardown intact; +2. `SIGTERM`, then wait `graces.disposeGraceMs`; +3. `SIGKILL`, then await the now-certain exit — a child that ignores EOF and traps `SIGTERM` cannot wedge dispose forever. + +The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; the EOF window is deliberately a separate — usually wider — grace than the signal tier, since a cooperative child's EOF teardown may itself await a signal-trapping grandchild plus a final flush. + +### `createIsolatedConfigDir(prefix, pinnedPath?)` + +A per-run isolated config directory for an external CLI child (the target of `CLAUDE_CONFIG_DIR` / `CODEX_HOME`-style redirection), so child behavior is a function of deployment config alone — never of whatever `~/.claude` / `~/.codex`-style state exists on the host. Returns an `IsolatedConfigDir` handle: `path` goes into the child env, `remove()` runs on dispose. + +- **Fresh (default)**: a private (0700) `mkdtemp` dir under the OS temp root; `remove()` deletes it best-effort (never rejects — a leftover temp dir beats a failed dispose) and is idempotent. +- **Pinned** (`pinnedPath` set): the path is returned as-is — never created, never removed. A deployment that pins a directory to share child state across runs owns that directory's lifecycle. + +## Testing + +`tests/subagent-process.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (including an rm-failure path proving `remove()` never rejects); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end. diff --git a/packages/subagent/subagent-process/package.json b/packages/subagent/subagent-process/package.json new file mode 100644 index 0000000000..218276be44 --- /dev/null +++ b/packages/subagent/subagent-process/package.json @@ -0,0 +1,30 @@ +{ + "name": "@deepseek-ai/dsh-subagent-process", + "description": "Shared out-of-process subagent machinery: credential env scrub, spawn-failure capture, child-exit waits, the EOF-to-SIGTERM-to-SIGKILL dispose ladder, and isolated config dirs (pure lib; registers nothing)", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "cordis": "^4.0.0-rc.6" + }, + "devDependencies": { + "cordis": "^4.0.0-rc.6" + } +} diff --git a/packages/subagent/subagent-process/src/index.ts b/packages/subagent/subagent-process/src/index.ts new file mode 100644 index 0000000000..b54681d3c7 --- /dev/null +++ b/packages/subagent/subagent-process/src/index.ts @@ -0,0 +1,207 @@ +/** + * Shared machinery for OUT-OF-PROCESS subagent backends — providers that spawn + * an external agent as a child process and must keep the parent deployment's + * credentials out of it, tear it down to quiescence, and isolate it from the + * host user's on-disk CLI state. The pieces: the credential env scrub + * ({@link SENSITIVE_ENV_PATTERN} / {@link buildChildEnv}), the spawn-failure + * capture ({@link spawnFailure}), the child-exit waits ({@link waitForExit} / + * {@link exitsWithin}), the stdin-EOF → SIGTERM → SIGKILL dispose ladder + * ({@link disposeChildProcess}), and the per-run isolated config dir + * ({@link createIsolatedConfigDir}). + * + * This package owns no provider and registers nothing; it is a pure library + * the out-of-process backend packages depend on (the `subagent-inprocess` + * shape, for the process boundary). Every tunable — the ladder's grace + * periods, a pinned config dir — is a PARAMETER here: defaults belong in each + * consuming plugin's Config, per the no-hardcoded-tunables rule. + * + * @module @deepseek-ai/dsh-subagent-process + */ + +import type { ChildProcess } from 'node:child_process' +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' + +/** + * Credential-shaped ambient env vars are NOT forwarded to a child by default + * (the parent harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a + * spawned process implicitly). Same pattern as the bash executor. The child + * agent needs its OWN credentials to reach a model — those are supplied + * explicitly via the `extra` layer of {@link buildChildEnv}, which lands AFTER + * the scrub, so an intended `DEEPSEEK_API_KEY` survives while an incidental + * `AWS_SECRET_ACCESS_KEY` does not. + */ +export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i + +/** + * The ambient env minus credential-shaped vars, plus the caller's explicit + * env. `PATH`, `HOME`, `TMPDIR`, locale, and proxy vars survive the scrub, so + * a child CLI runs normally; only {@link SENSITIVE_ENV_PATTERN}-shaped names + * are dropped. + * @param extra - explicit vars layered on top AFTER the scrub, so a + * credential-shaped name supplied deliberately still reaches the child. + * @returns the environment to spawn the child with. + */ +export function buildChildEnv(extra: Record): NodeJS.ProcessEnv { + const env: NodeJS.ProcessEnv = {} + for (const [key, value] of Object.entries(process.env)) { + if (!SENSITIVE_ENV_PATTERN.test(key)) env[key] = value + } + return { ...env, ...extra } +} + +/** + * Capture the child's spawn-level failure as a promise the run's result path + * can race. A spawn failure (e.g. `ENOENT` for a bad command) is emitted as an + * `error` EVENT, not a thrown exception — and without a listener Node treats + * it as an unhandled error and crashes the parent process. Call this in the + * SAME TICK as `spawn()`, so no window exists for the event to fire unheard. + * @param child - the just-spawned child process. + * @returns a promise that RESOLVES (never rejects) with the child's first + * `error` event; for a child that spawns cleanly it never settles. + */ +export function spawnFailure(child: ChildProcess): Promise { + return new Promise((resolve) => { + child.once('error', (err) => { resolve(err) }) + }) +} + +/** + * Resolve once the child process exits (any code/signal); immediate if it is + * already gone. + * @param child - the child process to await. + */ +export function waitForExit(child: ChildProcess): Promise { + if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve() + return new Promise(resolve => child.once('exit', () => { resolve() })) +} + +/** + * Race the child's exit against a timer. + * @param child - the child process to watch. + * @param ms - the wait window in milliseconds. + * @returns `true` if the child exits within `ms`, `false` on timeout. + */ +export function exitsWithin(child: ChildProcess, ms: number): Promise { + return Promise.race([ + waitForExit(child).then(() => true), + // `.unref()` so a pending grace timer never keeps the parent's loop alive. + new Promise(resolve => setTimeout(() => { resolve(false) }, ms).unref()), + ]) +} + +/** + * The two grace periods of the dispose ladder, supplied per call by the + * consuming backend — each plugin carries them as defaulted, validated + * `disposeEofGraceMs`/`disposeGraceMs` Config fields, so teardown timing is + * deployment-tunable and this library hardcodes nothing. + */ +export interface DisposeLadderGraces { + /** + * Tier-1 window (ms): after stdin EOF, how long the child gets to quiesce + * ON ITS OWN — flush durable state, tear down its own nested subprocesses — + * before the parent escalates to `SIGTERM`. A separate (usually WIDER) + * grace than {@link DisposeLadderGraces.disposeGraceMs}: a cooperative + * child's EOF-driven teardown may itself be waiting on a signal-trapping + * grandchild plus a final flush, needing more than one signal-grace of + * headroom. + */ + disposeEofGraceMs: number + /** Tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */ + disposeGraceMs: number +} + +/** + * Tear a child process down to QUIESCENCE: resolves only once the child has + * actually exited (or was already gone), never merely after requesting it. + * Three-tier escalation — + * + * 1. stdin EOF (when stdin is piped), then wait `disposeEofGraceMs`: a + * cooperative child quiesces on its own, its teardown and flushes intact; + * 2. `SIGTERM`, then wait `disposeGraceMs`; + * 3. `SIGKILL`, then await the (now-certain) exit — a child that ignores EOF + * and traps `SIGTERM` must not wedge dispose forever. + * + * @param child - the child process to tear down. + * @param graces - the two grace periods, from the consuming plugin's Config. + */ +export async function disposeChildProcess(child: ChildProcess, graces: DisposeLadderGraces): Promise { + // Already gone: nothing to reap. + if (child.exitCode !== null || child.signalCode !== null) return + // 1. Graceful: end the request stream (stdin EOF) and let the child quiesce + // on its own. Sending SIGTERM in the same tick (or too soon) would + // default-terminate a cooperative child mid-flush, orphaning its nested + // work. A child spawned without a stdin pipe skips straight to the wait. + child.stdin?.end() + if (await exitsWithin(child, graces.disposeEofGraceMs)) return + // 2. SIGTERM, escalating if the child still does not exit within the grace. + child.kill('SIGTERM') + if (await exitsWithin(child, graces.disposeGraceMs)) return + // 3. Force-kill and await the (now-certain) exit. + child.kill('SIGKILL') + await waitForExit(child) +} + +/** + * A per-run config directory handle for an external CLI child — the target of + * `CLAUDE_CONFIG_DIR` / `CODEX_HOME`-style redirection. Hand {@link path} to + * the child's environment; call {@link remove} on dispose. + */ +export interface IsolatedConfigDir { + /** The directory to point the child at. */ + path: string + /** + * Best-effort cleanup: removes the directory (recursively) iff this handle + * CREATED it — a pinned directory is never removed. Idempotent; never + * rejects (a leftover dir under the OS temp root is preferable to a failed + * dispose). + */ + remove(): Promise +} + +/** + * An isolated config dir for one child run, so the child's behavior is a + * function of deployment config alone — never of whatever `~/.claude` / + * `~/.codex`-style state happens to exist on the host machine. Two modes: + * + * - no `pinnedPath` (the default): creates a FRESH private (0700) `mkdtemp` + * dir under the OS temp root; {@link IsolatedConfigDir.remove} deletes it + * best-effort; + * - `pinnedPath` set (a deployment deliberately sharing state across runs): + * the pinned path is returned as-is — never created, never removed — the + * deployment owns that directory's lifecycle. + * + * @param prefix - the `mkdtemp` name prefix for a fresh dir (e.g. + * `dsh-subagent-codex-`); ignored when `pinnedPath` is set. + * @param pinnedPath - a deployment-pinned directory to use instead of a + * fresh one. + * @returns the directory handle: `path` for the child env, `remove()` for + * dispose. + */ +export async function createIsolatedConfigDir(prefix: string, pinnedPath?: string): Promise { + if (pinnedPath !== undefined) { + return { + path: pinnedPath, + remove(): Promise { + // A pinned dir is deployment-owned state (config the user asked to + // persist across runs); removing it here would destroy it. No-op. + return Promise.resolve() + }, + } + } + const path = await mkdtemp(join(tmpdir(), prefix)) + return { + path, + async remove(): Promise { + try { + await rm(path, { recursive: true, force: true }) + } catch { + // Best-effort by contract: swallows rm failures (EACCES/EBUSY-style — + // e.g. the dead child left an unreadable entry behind). The dir lives + // under the OS temp root, which reclaims it; failing dispose over + // cleanup would be worse than a leftover temp dir. + } + }, + } +} diff --git a/packages/subagent/subagent-process/tests/subagent-process.spec.ts b/packages/subagent/subagent-process/tests/subagent-process.spec.ts new file mode 100644 index 0000000000..c4828d8498 --- /dev/null +++ b/packages/subagent/subagent-process/tests/subagent-process.spec.ts @@ -0,0 +1,307 @@ +import { describe, expect, it } from 'vitest' +import { EventEmitter } from 'node:events' +import { existsSync } from 'node:fs' +import { chmod, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import type { ChildProcess } from 'node:child_process' +import { + buildChildEnv, + createIsolatedConfigDir, + disposeChildProcess, + exitsWithin, + SENSITIVE_ENV_PATTERN, + spawnFailure, + waitForExit, +} from '../src/index.ts' + +/** + * Unit tests for the shared out-of-process machinery. The env scrub and the + * isolated-config-dir helpers run against the REAL process env and REAL + * filesystem; the exit waits and the dispose ladder run against a scriptable + * fake child so each escalation tier's timing is driven deterministically + * (the ACP backend's suite exercises the same ladder against real + * subprocesses end to end). + */ + +/** What fells a scripted {@link FakeChild}. */ +type LethalTrigger = 'eof' | NodeJS.Signals + +/** Per-scenario script for a {@link FakeChild}. */ +interface FakeChildScript { + /** + * The one trigger that makes the child exit (SIGKILL always does, + * uncatchable, like a real process). Omitted: only SIGKILL fells it. + */ + diesOn?: LethalTrigger + /** Delay (ms) between the lethal trigger and the exit event. */ + delayMs?: number + /** `false` models a child spawned without a stdin pipe. */ + stdin?: boolean +} + +/** + * A scriptable stand-in for a ChildProcess carrying exactly the surface the + * helpers read: `exitCode`/`signalCode`, `stdin.end()`, `kill()`, and the + * `exit` event. + */ +class FakeChild extends EventEmitter { + exitCode: number | null = null + signalCode: NodeJS.Signals | null = null + readonly kills: NodeJS.Signals[] = [] + stdinEnded = false + readonly stdin: { end: () => void } | null + + constructor(private readonly script: FakeChildScript = {}) { + super() + this.stdin = script.stdin === false + ? null + : { end: () => { this.stdinEnded = true; this.maybeDie('eof') } } + } + + kill(signal: NodeJS.Signals): boolean { + this.kills.push(signal) + this.maybeDie(signal) + return true + } + + private maybeDie(trigger: LethalTrigger): void { + // SIGKILL is uncatchable — it always fells the child; any other trigger + // only when the scenario scripts it as the lethal one. + if (trigger !== 'SIGKILL' && this.script.diesOn !== trigger) return + setTimeout(() => { + if (trigger === 'eof') this.exitCode = 0 + else this.signalCode = trigger + this.emit('exit', this.exitCode, this.signalCode) + }, this.script.delayMs ?? 0) + } +} + +/** The helpers take a real ChildProcess; the fake carries the read surface. */ +function asChild(fake: FakeChild): ChildProcess { + return fake as unknown as ChildProcess +} + +describe('buildChildEnv / SENSITIVE_ENV_PATTERN', () => { + it('drops credential-shaped ambient vars (KEY/SECRET/TOKEN, case-insensitive)', () => { + process.env.DSH_PROC_TEST_API_KEY = 'leak' + process.env.dsh_proc_test_secret = 'leak' + process.env.DSH_PROC_TEST_TOKEN = 'leak' + try { + const env = buildChildEnv({}) + expect(env.DSH_PROC_TEST_API_KEY).toBeUndefined() + expect(env.dsh_proc_test_secret).toBeUndefined() + expect(env.DSH_PROC_TEST_TOKEN).toBeUndefined() + } finally { + delete process.env.DSH_PROC_TEST_API_KEY + delete process.env.dsh_proc_test_secret + delete process.env.DSH_PROC_TEST_TOKEN + } + }) + + it('forwards normal ambient vars', () => { + expect(SENSITIVE_ENV_PATTERN.test('PATH')).toBe(false) + expect(buildChildEnv({}).PATH).toBe(process.env.PATH) + }) + + it('layers extras AFTER the scrub, so a deliberate credential-shaped name survives', () => { + process.env.DSH_PROC_TEST_EXTRA_TOKEN = 'ambient-leak' + try { + const env = buildChildEnv({ DSH_PROC_TEST_EXTRA_TOKEN: 'explicit' }) + // The ambient value was scrubbed; ONLY the explicit opt-in reaches the child. + expect(env.DSH_PROC_TEST_EXTRA_TOKEN).toBe('explicit') + } finally { + delete process.env.DSH_PROC_TEST_EXTRA_TOKEN + } + }) + + it('an extra overrides the ambient value of a non-credential var', () => { + process.env.DSH_PROC_TEST_PLAIN = 'ambient' + try { + expect(buildChildEnv({ DSH_PROC_TEST_PLAIN: 'override' }).DSH_PROC_TEST_PLAIN).toBe('override') + } finally { + delete process.env.DSH_PROC_TEST_PLAIN + } + }) +}) + +describe('spawnFailure', () => { + it('resolves (never rejects) with the first error event', async () => { + const fake = new FakeChild() + const failure = spawnFailure(asChild(fake)) + const err = new Error('spawn ENOENT') + fake.emit('error', err) + await expect(failure).resolves.toBe(err) + }) + + it('never settles for a child that spawns cleanly and exits', async () => { + const fake = new FakeChild({ diesOn: 'SIGTERM' }) + const failure = spawnFailure(asChild(fake)) + fake.kill('SIGTERM') + await waitForExit(asChild(fake)) + // A clean lifecycle emits `exit`, never `error` — the capture stays + // pending forever, so a race against it is decided by the other arms. + const settled = await Promise.race([ + failure.then(() => 'settled'), + new Promise(resolve => setTimeout(() => { resolve('pending') }, 30)), + ]) + expect(settled).toBe('pending') + }) +}) + +describe('waitForExit / exitsWithin', () => { + it('resolves immediately for a child that already exited by code', async () => { + const fake = new FakeChild() + fake.exitCode = 0 + await expect(waitForExit(asChild(fake))).resolves.toBeUndefined() + }) + + it('resolves immediately for a child that already died by signal', async () => { + const fake = new FakeChild() + fake.signalCode = 'SIGTERM' + await expect(waitForExit(asChild(fake))).resolves.toBeUndefined() + }) + + it('resolves on the exit event of a live child', async () => { + const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 }) + const exited = waitForExit(asChild(fake)) + fake.kill('SIGTERM') + await expect(exited).resolves.toBeUndefined() + expect(fake.signalCode).toBe('SIGTERM') + }) + + it('exitsWithin resolves true when the child exits inside the window', async () => { + const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 }) + fake.kill('SIGTERM') + await expect(exitsWithin(asChild(fake), 1000)).resolves.toBe(true) + }) + + it('exitsWithin resolves false on timeout for a child that never exits', async () => { + const fake = new FakeChild() // nothing short of SIGKILL fells it; no signal sent + await expect(exitsWithin(asChild(fake), 20)).resolves.toBe(false) + }) +}) + +describe('disposeChildProcess', () => { + it('returns immediately for an already-exited child (no EOF, no signals)', async () => { + const fake = new FakeChild() + fake.exitCode = 0 + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 }) + expect(fake.stdinEnded).toBe(false) + expect(fake.kills).toEqual([]) + }) + + it('returns immediately for a child already dead by signal', async () => { + const fake = new FakeChild() + fake.signalCode = 'SIGKILL' + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 }) + expect(fake.stdinEnded).toBe(false) + expect(fake.kills).toEqual([]) + }) + + it('tier 1: a cooperative child quiesces on stdin EOF — no signal is ever sent', async () => { + const fake = new FakeChild({ diesOn: 'eof', delayMs: 5 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 }) + expect(fake.stdinEnded).toBe(true) + expect(fake.kills).toEqual([]) + expect(fake.exitCode).toBe(0) + }) + + it('tier 2: a child that ignores EOF but honors SIGTERM dies on the middle rung', async () => { + const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }) + expect(fake.stdinEnded).toBe(true) + expect(fake.kills).toEqual(['SIGTERM']) + expect(fake.signalCode).toBe('SIGTERM') + }) + + it('tier 3: a SIGTERM-trapping child is SIGKILLed, and dispose resolves only after the exit', async () => { + const fake = new FakeChild({ delayMs: 5 }) // only SIGKILL fells it + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }) + expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL']) + // Quiescence, not a request: at resolution the child has ACTUALLY exited + // (the exit event landed, despite the scripted post-SIGKILL delay). + expect(fake.signalCode).toBe('SIGKILL') + }) + + it('walks the ladder for a child spawned without a stdin pipe', async () => { + const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 }) + await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }) + expect(fake.kills).toEqual(['SIGTERM']) + }) +}) + +describe('createIsolatedConfigDir', () => { + it('creates a fresh private mkdtemp dir under the OS temp root', async () => { + const dir = await createIsolatedConfigDir('dsh-subagent-process-test-') + try { + expect(dir.path.startsWith(join(tmpdir(), 'dsh-subagent-process-test-'))).toBe(true) + const st = await stat(dir.path) + expect(st.isDirectory()).toBe(true) + // Private (0700) per the defensive-patterns temp-dir rule. + expect(st.mode & 0o777).toBe(0o700) + } finally { + await dir.remove() + } + }) + + it('creates a distinct dir per call (per-run isolation)', async () => { + const a = await createIsolatedConfigDir('dsh-subagent-process-test-') + const b = await createIsolatedConfigDir('dsh-subagent-process-test-') + try { + expect(a.path).not.toBe(b.path) + } finally { + await a.remove() + await b.remove() + } + }) + + it('remove() deletes a fresh dir recursively and is idempotent', async () => { + const dir = await createIsolatedConfigDir('dsh-subagent-process-test-') + await writeFile(join(dir.path, 'settings.json'), '{}') + await dir.remove() + expect(existsSync(dir.path)).toBe(false) + // Second remove: nothing left to delete, still resolves. + await expect(dir.remove()).resolves.toBeUndefined() + }) + + it('returns a pinned dir verbatim and NEVER removes it', async () => { + const pinned = await mkdtemp(join(tmpdir(), 'dsh-subagent-process-pinned-')) + try { + const dir = await createIsolatedConfigDir('ignored-prefix-', pinned) + expect(dir.path).toBe(pinned) + await dir.remove() + // The deployment owns a pinned dir's lifecycle — remove() must not touch it. + expect(existsSync(pinned)).toBe(true) + } finally { + await rm(pinned, { recursive: true, force: true }) + } + }) + + it('does not create a missing pinned path (the deployment owns its lifecycle)', async () => { + const missing = join(tmpdir(), `dsh-subagent-process-missing-${process.pid}`) + const dir = await createIsolatedConfigDir('ignored-prefix-', missing) + expect(dir.path).toBe(missing) + expect(existsSync(missing)).toBe(false) + await dir.remove() + expect(existsSync(missing)).toBe(false) + }) + + it('remove() is best-effort: an rm failure resolves instead of rejecting', async () => { + const dir = await createIsolatedConfigDir('dsh-subagent-process-locked-') + const locked = join(dir.path, 'locked') + await mkdir(locked) + await writeFile(join(locked, 'entry'), 'x') + // An unreadable, unwritable non-empty subdir makes recursive rm fail + // (EACCES on readdir/unlink) for a non-root user. + await chmod(locked, 0o000) + try { + await expect(dir.remove()).resolves.toBeUndefined() + // rm really did fail — the locked subtree is still there. + expect(existsSync(locked)).toBe(true) + } finally { + await chmod(locked, 0o700) + await rm(dir.path, { recursive: true, force: true }) + } + }) +}) diff --git a/packages/subagent/subagent-process/tsconfig.json b/packages/subagent/subagent-process/tsconfig.json new file mode 100644 index 0000000000..749cb0208e --- /dev/null +++ b/packages/subagent/subagent-process/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 32ffa0d389..359b68b6d5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -594,6 +594,9 @@ importers: '@deepseek-ai/dsh-subagent': specifier: workspace:^ version: link:../subagent + '@deepseek-ai/dsh-subagent-process': + specifier: workspace:^ + version: link:../subagent-process cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -671,6 +674,12 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/subagent/subagent-process: + devDependencies: + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/subagent/subagent-spawn: dependencies: schemastery: diff --git a/tsconfig.build.json b/tsconfig.build.json index 3d99ad4e28..21fa726927 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -50,6 +50,7 @@ { "path": "./packages/support/subagent-mock" }, { "path": "./packages/subagent/tool-subagent" }, { "path": "./packages/subagent/subagent-inprocess" }, + { "path": "./packages/subagent/subagent-process" }, { "path": "./packages/subagent/subagent-spawn" }, { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, diff --git a/tsconfig.json b/tsconfig.json index 2091283c93..c4127b2b5d 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -61,6 +61,7 @@ { "path": "./packages/support/subagent-mock" }, { "path": "./packages/subagent/tool-subagent" }, { "path": "./packages/subagent/subagent-inprocess" }, + { "path": "./packages/subagent/subagent-process" }, { "path": "./packages/subagent/subagent-spawn" }, { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, From e6bd6cc9beb7a2a73907bebf092cffefee6840de Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 19:32:42 +0800 Subject: [PATCH 059/119] fix(compact): count the logged session prefix toward token pressure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ds-review-bot critical: compactIfNeeded estimated pressure from the derived history + system prompt only, but every loop-built request also carries EpochHeader.messagePrefix in front of the history — a deployment at the window edge would under-estimate by exactly the prefix, skip compaction, and ship an over-window request. BasicCompactService now gates on estimatePressure(): the session prefix read from the log's folded header + the derived history + the system prompt. The fold is exact from the instance's second request on (and from a resumed instance's first — the previous instance logged its prefix); it is absent only before a fresh session's first request, where the history is a single prompt and compaction is moot. Compaction itself still shrinks history only — a prefix that alone approaches the window is a configuration error no compactor fixes, same as the documented single-unit-overflow stance. --- packages/compact/compact-basic/README.md | 2 +- packages/compact/compact-basic/src/index.ts | 37 ++++++++++++++++--- .../compact-basic/tests/compact-basic.spec.ts | 23 ++++++++++++ 3 files changed, 55 insertions(+), 7 deletions(-) diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md index f4400911c6..86ba3c32a3 100644 --- a/packages/compact/compact-basic/README.md +++ b/packages/compact/compact-basic/README.md @@ -8,7 +8,7 @@ This is the implementation tier of the compaction capability — see the [interf The abstract contract states only WHAT compaction does; this backend owns every HOW decision: -- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). +- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the logged session prefix (`EpochHeader.messagePrefix` from the header fold — the `agent/session-prefix` product rides every request in front of the history, so omitting it would under-estimate pressure by exactly the prefix) + the derived history + the system prompt. - **Retention policy** — `compactIfNeeded()` walks the surface nodes tail→head summing per-node token estimates, and retains the smallest tail-run of WHOLE units (a closed step, or a single no-step node such as a pre-step `user/message` or inter-step `steering/message`) whose total reaches `retainTokens`; everything older is compacted. Retention is **turn-agnostic** — turn boundaries play no role, so a single runaway turn that alone exceeds the window compacts its OWN early closed steps rather than being retained verbatim (the failure mode that motivated dropping turn-protection: a tool-heavy turn must stay compactable or the harness dies exactly when compaction is needed). The only structural guard is **tool-pairing balance**: the compacted region's edges are balanced cuts on the surface (no unanswered tool-call crosses either edge), so it never splits a step's `assistant/message` tool-calls from their `tool/result`s. When the only compactable content left is an un-splittable open tail step, it declines (returns `null`) and retries once an older step closes. **Single-unit overflow is out of scope, by design**: if one retained unit (a single closed step, or a large pasted `user/message`) ALONE exceeds the budget, compaction cannot help and the call may go out over-budget — bounding an individual unit's size is a separate concern. `compactRegion()` enforces tool-pairing balance strictly, throwing on a boundary that would split a step. `dsh-session` exports `isToolPairingBalanced` for the check. - **Dynamic convergence** — no static summary-length config pretends to bound what the model will write. If framing/estimator/system overhead leaves the compacted surface above threshold, `compactIfNeeded()` re-compacts the head checkpoint up to `compactionRetries` extra times; if it still cannot get below threshold, it throws. A summary whose estimated stored size is not smaller than the shadowed content fails closed before it mutates the surface. - **Summarization** — `summarize()`: a `GenerateOptions` request assembled via `BlockAssembler` with a fixed system prompt that asks for a structured checkpoint (Primary Request and Intent · Key Technical Concepts · Files and Code · Errors and Fixes · Pending Tasks · Current Work · Next Step · Critical Context), every section mandatory, exact paths/commands/identifiers preserved. The request is a direct one-shot `ctx.llm.stream()` call — NOT a loop step, so it does not run `agent/request` (that seam shapes the loop's conversation requests); the model comes from `summarizationModel` falling back to the agent's own, and per-call routing happens at `llm/stream` like any other direct call. `maxTokens` is the provider-side generation cap; only text blocks from the model's reply are kept before the checkpoint is stored (reasoning is dropped so private chain-of-thought never leaks into the durable summary, and a stray `tool-call` is dropped so the synthesized `user/message` summary cannot land an orphaned call with no matching `tool-result`). The compacted region is flattened to a plain-text transcript first: text and reasoning contribute their text, and every non-text block (tool-call, tool-result, plugin-added types) contributes a type-tagged placeholder (`[tool-call: name(args)]`, `[tool-result: …]`, …) so the summarizer is told what existed rather than silently dropping it. diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts index 03f7c9ab4b..87765b574e 100644 --- a/packages/compact/compact-basic/src/index.ts +++ b/packages/compact/compact-basic/src/index.ts @@ -187,7 +187,7 @@ export class BasicCompactService extends CompactService { try { const result = await this.compactIfNeeded(agent, fullSystemPrompt, signal) if (result) { - const after = this.estimateTokens(agent.session.deriveMessages(), fullSystemPrompt) + const after = this.estimatePressure(agent.session, fullSystemPrompt) ctx.logger.info( `compaction: shadowed ${result.shadowedSeqs.length} surface nodes ` + `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, ` + @@ -359,11 +359,19 @@ export class BasicCompactService extends CompactService { // ---- Core API (implements the abstract contract) ---- /** - * The sole token-pressure gate: estimate the current surface-derived history, - * and if it exceeds the threshold (`contextWindow * thresholdRatio`), compact + * The sole token-pressure gate: estimate the NEXT request's pressure — the + * logged session prefix + the surface-derived history + the system prompt + * ({@link estimatePressure}) — and if it exceeds the threshold + * (`contextWindow * thresholdRatio`), compact * the oldest surface nodes outside the `retainTokens` budget. The auto- * compaction listener delegates here rather than pre-checking, so this is the - * only place the decision lives. + * only place the decision lives. The prefix counts because every request + * carries it in front of the history (`EpochHeader.messagePrefix`) even + * though it is not derived history — omitting it would under-estimate by + * exactly the prefix and let a deployment at the window edge skip + * compaction, then ship an over-window request. Compaction itself can only + * shrink HISTORY: a prefix that alone approaches the window is a + * configuration error no compactor fixes. * * Retention is a UNIFORM tail→head walk over the whole surface — turn * boundaries play NO role. Walking node-by-node from the tail and summing @@ -393,7 +401,7 @@ export class BasicCompactService extends CompactService { const threshold = Math.floor(this.config.contextWindow * this.config.thresholdRatio) let result: CompactionResult | null = null for (let attempt = 0; attempt <= this.config.compactionRetries; attempt++) { - const totalTokens = this.estimateTokens(session.deriveMessages(), fullSystemPrompt) + const totalTokens = this.estimatePressure(session, fullSystemPrompt) if (totalTokens < threshold) return result const range = this._compactableRange(session) @@ -407,7 +415,7 @@ export class BasicCompactService extends CompactService { result = await this.compactRegion(session, range.start, range.end, agent, signal) } - const totalTokens = this.estimateTokens(session.deriveMessages(), fullSystemPrompt) + const totalTokens = this.estimatePressure(session, fullSystemPrompt) if (totalTokens < threshold) return result throw new Error( @@ -416,6 +424,23 @@ export class BasicCompactService extends CompactService { ) } + /** + * Estimated token pressure of the NEXT request: the logged session prefix + * (`EpochHeader.messagePrefix` from the header fold — request-only messages + * the loop sends in front of the derived history), the derived history, and + * the system prompt. The fold is exact from the loop instance's second + * request on (and from a resumed instance's first — the previous instance + * logged its prefix); it is absent only before a fresh session's first + * request, where the history is a single prompt and compaction is moot. + * @param session - the session whose next request is being estimated. + * @param fullSystemPrompt - the assembled system prompt (counts toward pressure). + * @returns the estimated token total the next request will carry. + */ + estimatePressure(session: Session, fullSystemPrompt: string): number { + const sessionPrefix = session.requestHeader()?.messagePrefix ?? [] + return this.estimateTokens([...sessionPrefix, ...session.deriveMessages()], fullSystemPrompt) + } + override async compactRegion( session: Session, start: number, diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index 990d60190a..b58e50f4c3 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -557,6 +557,29 @@ describe('BasicCompactService.compactIfNeeded', () => { expect(result!.shadowedSeqs.length).toBeGreaterThan(0) }) + it('counts the logged session prefix toward pressure (every request carries it in front of the history)', async () => { + const svc = createTestService({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 10 }) + const session = multiTurnSession(3, 1) // 6 derived messages ≈ 84 estimated tokens — under the 100 threshold alone + expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull() + + // The loop records the composed agent/session-prefix product on the + // request header; it rides every request, so pressure must include it. + session.append('request/header', { + header: { + config: { model: 'm' }, + messagePrefix: [ + { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] }, + { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] }, + ], + }, + reason: 'initial', + }) + const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) + expect(result).not.toBeNull() + // The prefix itself is NOT history: compaction shadowed surface nodes only. + expect(session.requestHeader()?.messagePrefix).toHaveLength(2) + }) + it('returns the first compaction result when a zero-retry pass converges after the loop', async () => { // With compactionRetries=0 there is no next-loop threshold check after the // first mutation, so the success path is the post-loop `return result`. From 765052a7d1a60d884558f4e6d6840b9b10b6a6d4 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 20:30:10 +0800 Subject: [PATCH 060/119] fix(agent-loop): compose the session prefix before pre-step; hand it to the pressure gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ds-review-bot critical (follow-up): on the first step of a resumed or seeded/forked instance, auto-compaction ran before runStep composed this instance's prefix, so the gate read the PREVIOUS instance's logged prefix from the header fold — a contributor that grew across resume/fork (skills added, AGENTS.md grown: exactly the environment-dependent case) could under-gate and ship an over-window first request. The loop now composes agent/session-prefix before the instance's first agent/pre-step (still once per instance; runStep just reads the cache), and agent/pre-step carries the composed prefix to its listeners. CompactService.compactIfNeeded gains the sessionPrefix parameter; BasicCompactService.estimatePressure gates on the handed value — the header-fold read is gone, so the estimate is exact at every step including a resumed/forked instance's first. Composition moving before the boundary snapshot also means a composing listener's session append now joins the CURRENT request (documented on the seam). New coverage: composition precedes pre-step and the seam receives the composed prefix; cancel and disposal landing inside the composition window drop the step cleanly; the compact gate test hands the prefix directly. --- docs/architecture.md | 3 +- docs/cordis-catalog/events.md | 22 +++--- docs/cordis-catalog/services.md | 6 +- docs/event-producer-consumer.md | 14 ++-- .../2026-07-05-reconstructable-requests.md | 2 +- packages/compact/compact-basic/README.md | 2 +- packages/compact/compact-basic/src/index.ts | 34 +++++---- .../compact-basic/tests/compact-basic.spec.ts | 38 +++++----- packages/compact/compact/src/index.ts | 24 ++++-- .../compact/compact/tests/compact.spec.ts | 6 +- packages/core/agent-loop/README.md | 7 +- packages/core/agent-loop/src/loop.ts | 75 ++++++++++++------- packages/core/agent-loop/tests/cancel.spec.ts | 63 ++++++++++++++++ .../agent-loop/tests/interception.spec.ts | 27 +++++++ packages/core/agent/README.md | 4 +- packages/core/agent/src/types.ts | 24 ++++-- 16 files changed, 244 insertions(+), 107 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index bfec8b1d84..908bb63664 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -70,10 +70,11 @@ forever: STEP loop: drain steering assemble system prompt and tool schemas + agent/session-prefix (first step) agent/pre-step 'step/start' snapshot the derived messages (the reconstruction boundary) - agent/request (config only) -> agent/session-prefix (first request) -> log request/header -> llm/stream (frozen) + agent/request (config only) -> log request/header -> llm/stream (frozen) 'assistant/chunk' agent/step-result 'assistant/message' diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index e9b213c2fa..8b820168b3 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -47,21 +47,21 @@ 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:460`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:472`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step's `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`. `step` is the number of the step about to start. The loop awaits `ctx.serial('agent/pre-step', …)` after assembling the system prompt, then opens the step and derives the request history ONCE from whatever the surface now holds. This is where compaction belongs: it mutates the session surface in place (shadowing an older range with a summary node) with its log-only `compact/*` records cleanly outside any step, and the single subsequent derive reflects the mutation — so there is no double-derive and no listener can see (or be expected to act on) an assembled `messages` array that does not exist yet. -Serial (awaited in registration order), not a waterfall: a listener mutates the surface as a side effect; there is nothing to transform, but the loop must wait for the mutation to complete before opening the step and deriving. Cordis `serial` bails early if a listener returns a bail value; this event is typed and documented as `void`, so listeners must not return a semantic veto value. `fullSystemPrompt` is the assembled prompt a listener needs to measure pressure (the system prompt counts toward the budget). `signal` cancels any in-flight work a listener starts (e.g. a summarization model call). +Serial (awaited in registration order), not a waterfall: a listener mutates the surface as a side effect; there is nothing to transform, but the loop must wait for the mutation to complete before opening the step and deriving. Cordis `serial` bails early if a listener returns a bail value; this event is typed and documented as `void`, so listeners must not return a semantic veto value. `fullSystemPrompt` is the assembled prompt a listener needs to measure pressure (the system prompt counts toward the budget), and `sessionPrefix` is the instance's composed agent/session-prefix product for the same reason — every request carries it in front of the derived history, and it is composed BEFORE this seam fires precisely so a pressure gate counts the prefix the request will actually send (never a stale logged one). `signal` cancels any in-flight work a listener starts (e.g. a summarization model call). ```ts cordis-catalog -'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal): Promise | void +'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise | void ``` -Types: [Agent](../core-data-structures/core.md) +Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:350`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:357`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -73,7 +73,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a 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:363`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:370`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -97,11 +97,11 @@ Waterfall: shape the step's call configuration — model switching, sampling ove Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:387`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:394`](../../packages/core/agent/src/types.ts) ### `agent/session-prefix` — waterfall -Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider's system slot) on every request this loop instance sends. Fired ONCE per loop instance, lazily on its first request-building step; the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the instance's anchoring `'initial'`/`'resume'` header snapshot, and reused verbatim for every subsequent request — never recomputed mid-session, so the provider prefix cache holds by construction (a process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` snapshot). +Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider's system slot) on every request this loop instance sends. Fired ONCE per loop instance, lazily before its first step's agent/pre-step seam — BEFORE the pre-step so a token-pressure gate (compaction) counts the prefix this instance will actually send, never a previous instance's logged one. The composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the instance's anchoring `'initial'`/`'resume'` header snapshot, and reused verbatim for every subsequent request — never recomputed mid-session, so the provider prefix cache holds by construction (a process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` snapshot). Composition runs outside the step, before the boundary snapshot: a composing listener's session append joins the CURRENT request's derived history. This is the home for session-stable openers the model must always see but that must NOT become durable history — a skills catalog, an AGENTS.md digest, a workspace baseline: `Session.deriveMessages()` never returns the prefix, and the header events are its only durable record, so the request stays reconstructable from the log. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, a `tools/post-execute` decision's `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter. @@ -113,7 +113,7 @@ The seed is a frozen empty list; a contributing listener returns a NEW array — Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:425`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:437`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -149,7 +149,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:435`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:447`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -161,7 +161,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:448`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:460`](../../packages/core/agent/src/types.ts) ## `fs/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 26126c4481..5faf97edcd 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -98,11 +98,13 @@ Implementations MUST honor: - **Blocking**: no compaction begins while another is in progress for the same session. The recommended mechanism is the log-recorded lock — append `compact/start` before the slow work and `compact/end` after (even on failure) — so the lock is visible to replay and crash recovery. ```ts cordis-catalog -abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, signal: AbortSignal, ): Promise +abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise ``` -Source: [`packages/compact/compact/src/index.ts:63`](../../packages/compact/compact/src/index.ts) +Types: [Message](../core-data-structures/core.md) + +Source: [`packages/compact/compact/src/index.ts:64`](../../packages/compact/compact/src/index.ts) ## `ctx.fs` — `FileSystem` (abstract seam) diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 534a0af269..19a2d4b1c0 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -9,16 +9,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac | --- | --- | --- | --- | --- | | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:460`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:350`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:363`](../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/error` | `emit` | [`packages/core/agent/src/types.ts:472`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:357`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:370`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:290`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:387`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:425`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:394`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:437`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:305`](../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:281`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:435`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:448`](../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/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:447`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:460`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../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:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md index 20bd1e3005..73967c14b6 100644 --- a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -22,7 +22,7 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro **The header.** The request's non-history half — `EpochHeader`: call config (`LlmCallConfig`: model + sampling scalars), rendered system prompt, assembled tool schemas, and the session prefix (`messagePrefix`, below) — is logged session state, in canonical form (empty system/tools/prefix ≡ absent). Two log-only, turn-enclosed events in dsh-session carry it: `request/header`, a full snapshot with reason `'initial' | 'resume' | 'fallback'`, and `request/header-delta`, an amendment (`SystemDelta`: a common-prefix/suffix line trim; `ToolsDelta`: name-keyed added/removed/changed; `config`: replaced whole; `messagePrefix`: replaced whole, an empty array encoding the transition to absence — an arm the loop never exercises in practice, kept for codec totality). The pure trio `foldRequestHeader` / `diffHeader` / `applyHeaderDelta` reconstructs; the live session tracks the fold with the same lazy cursor as the message cache. Snapshots anchor the fold where a fold needs anchors — conversation birth and process boundaries — and each loop instance appends one on its first request (`'initial'` when the log has none, `'resume'` otherwise, even when nothing changed: the boundary itself is a recorded fact, and cross-restart drift becomes attributable while an unchanged header resumes byte-identical). Deltas are an encoding optimization with a safety valve, never a correctness dependency: the writer verifies `applyHeaderDelta(prev, delta)` reproduces the new header exactly and records a `'fallback'` snapshot when the encoding cannot express a change (a pure tool reordering), so a well-formed log always folds. -**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → `agent/pre-step` (compaction's surface mutations land before derivation) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → on the instance's FIRST request only, the `agent/session-prefix` waterfall — request-ONLY messages fronting the entire derived history (a frozen empty seed, contributions returned as an extension of `next()`; the home for session-stable openers that must NOT become history — a skills catalog, an AGENTS.md digest), deep-frozen and cached on the instance so reuse is structural and the prefix cannot drift mid-session — → the header event the request owes the log, carrying the prefix as `messagePrefix` (no session event carries it, so the header is its only durable record; resume = a new instance = a recompose, anchored by its `'resume'` snapshot) → build `GenerateOptions` from `messagePrefix + snapshot` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's per-instance bookkeeping is one boolean plus the cached prefix: whether this instance has logged its anchoring snapshot, and what it composed. +**The loop, transmission-stateless.** Per step: render assembly (every step — value comparison needs no change-signal discipline, and a section that varies per step surfaces as a *logged* header event per step instead of a silent bust) → on the instance's FIRST step only, the `agent/session-prefix` waterfall — request-ONLY messages fronting the entire derived history (a frozen empty seed, contributions returned as an extension of `next()`; the home for session-stable openers that must NOT become history — a skills catalog, an AGENTS.md digest), deep-frozen and cached on the instance so reuse is structural and the prefix cannot drift mid-session — → `agent/pre-step`, carrying the composed prefix (compaction's surface mutations land before derivation, and its pressure gate counts the prefix this instance will actually send — never a previous instance's logged one, which could under-gate a resumed/forked instance whose contributor grew) → **messages snapshot, then `step/start` appended as the next operation in the same synchronous frame** → seed the call config (first request of the instance: from `AgentOptions`, so explicit options always beat the logged baseline — fork model-overrides and resume reconfiguration stay correct; afterwards: from the folded header) → the `agent/request` waterfall, re-typed `(agent, turn, step, config: LlmCallConfig, next) → LlmCallConfig` — a frozen seed and a returned replacement are ALL a listener shapes; durable content flows through the log channels (`inject()`, steering, prompt-submit `additionalContext`, sections via `system-prompt/assemble`) — → the header event the request owes the log, carrying the prefix as `messagePrefix` (no session event carries it, so the header is its only durable record; resume = a new instance = a recompose, anchored by its `'resume'` snapshot) → build `GenerateOptions` from `messagePrefix + snapshot` + header, deep-freeze (`deepFreeze` exempts the `AbortSignal`, the one live control channel — freezing one breaks `AbortController.abort()`), dispatch. The loop's per-instance bookkeeping is one boolean plus the cached prefix: whether this instance has logged its anchoring snapshot, and what it composed. **The reconstruction boundary is `step/start`, unconditionally.** A step's messages are the derivation over `events[0..stepStartSeq)`. Because the snapshot precedes the `step/start` append in the same synchronous frame, nothing can enter this request past the boundary: an `agent.inject()` from an `agent/request` listener (or any concurrent task, or a `session/event` listener firing on `step/start` itself) lands in the log after the boundary and joins the NEXT request. For waterfall-window appends this matches the prior loop (it also derived before its waterfall); for a synchronous `step/start` listener it is a deliberate change — such a listener could previously reach the current request — and `agent/pre-step` is the sanctioned seam for content that must affect the CURRENT request. A step's header for reconstruction is the fold after its own `request/header*` event (which sits between its `step/start` and first response event) or the fold carried forward. diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md index 86ba3c32a3..a06e74b818 100644 --- a/packages/compact/compact-basic/README.md +++ b/packages/compact/compact-basic/README.md @@ -8,7 +8,7 @@ This is the implementation tier of the compaction capability — see the [interf The abstract contract states only WHAT compaction does; this backend owns every HOW decision: -- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the logged session prefix (`EpochHeader.messagePrefix` from the header fold — the `agent/session-prefix` product rides every request in front of the history, so omitting it would under-estimate pressure by exactly the prefix) + the derived history + the system prompt. +- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the session prefix (the `agent/session-prefix` product — composed by the loop BEFORE the pre-step seam and handed through it, so the gate counts the prefix this instance will actually send in front of the history, never a stale logged one) + the derived history + the system prompt. - **Retention policy** — `compactIfNeeded()` walks the surface nodes tail→head summing per-node token estimates, and retains the smallest tail-run of WHOLE units (a closed step, or a single no-step node such as a pre-step `user/message` or inter-step `steering/message`) whose total reaches `retainTokens`; everything older is compacted. Retention is **turn-agnostic** — turn boundaries play no role, so a single runaway turn that alone exceeds the window compacts its OWN early closed steps rather than being retained verbatim (the failure mode that motivated dropping turn-protection: a tool-heavy turn must stay compactable or the harness dies exactly when compaction is needed). The only structural guard is **tool-pairing balance**: the compacted region's edges are balanced cuts on the surface (no unanswered tool-call crosses either edge), so it never splits a step's `assistant/message` tool-calls from their `tool/result`s. When the only compactable content left is an un-splittable open tail step, it declines (returns `null`) and retries once an older step closes. **Single-unit overflow is out of scope, by design**: if one retained unit (a single closed step, or a large pasted `user/message`) ALONE exceeds the budget, compaction cannot help and the call may go out over-budget — bounding an individual unit's size is a separate concern. `compactRegion()` enforces tool-pairing balance strictly, throwing on a boundary that would split a step. `dsh-session` exports `isToolPairingBalanced` for the check. - **Dynamic convergence** — no static summary-length config pretends to bound what the model will write. If framing/estimator/system overhead leaves the compacted surface above threshold, `compactIfNeeded()` re-compacts the head checkpoint up to `compactionRetries` extra times; if it still cannot get below threshold, it throws. A summary whose estimated stored size is not smaller than the shadowed content fails closed before it mutates the surface. - **Summarization** — `summarize()`: a `GenerateOptions` request assembled via `BlockAssembler` with a fixed system prompt that asks for a structured checkpoint (Primary Request and Intent · Key Technical Concepts · Files and Code · Errors and Fixes · Pending Tasks · Current Work · Next Step · Critical Context), every section mandatory, exact paths/commands/identifiers preserved. The request is a direct one-shot `ctx.llm.stream()` call — NOT a loop step, so it does not run `agent/request` (that seam shapes the loop's conversation requests); the model comes from `summarizationModel` falling back to the agent's own, and per-call routing happens at `llm/stream` like any other direct call. `maxTokens` is the provider-side generation cap; only text blocks from the model's reply are kept before the checkpoint is stored (reasoning is dropped so private chain-of-thought never leaks into the durable summary, and a stray `tool-call` is dropped so the synthesized `user/message` summary cannot land an orphaned call with no matching `tool-result`). The compacted region is flattened to a plain-text transcript first: text and reasoning contribute their text, and every non-text block (tool-call, tool-result, plugin-added types) contributes a type-tagged placeholder (`[tool-call: name(args)]`, `[tool-result: …]`, …) so the summarizer is told what existed rather than silently dropping it. diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts index 87765b574e..d895784c5c 100644 --- a/packages/compact/compact-basic/src/index.ts +++ b/packages/compact/compact-basic/src/index.ts @@ -183,11 +183,11 @@ export class BasicCompactService extends CompactService { // log-only `compact/*` records and the replacement node cleanly outside a // step, so a crash mid-compaction leaves an inert orphan the turn-repair // closes — never a half-open step. - ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, signal: AbortSignal) => { + ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal) => { try { - const result = await this.compactIfNeeded(agent, fullSystemPrompt, signal) + const result = await this.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal) if (result) { - const after = this.estimatePressure(agent.session, fullSystemPrompt) + const after = this.estimatePressure(agent.session, fullSystemPrompt, sessionPrefix) ctx.logger.info( `compaction: shadowed ${result.shadowedSeqs.length} surface nodes ` + `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, ` + @@ -360,7 +360,7 @@ export class BasicCompactService extends CompactService { /** * The sole token-pressure gate: estimate the NEXT request's pressure — the - * logged session prefix + the surface-derived history + the system prompt + * session prefix + the surface-derived history + the system prompt * ({@link estimatePressure}) — and if it exceeds the threshold * (`contextWindow * thresholdRatio`), compact * the oldest surface nodes outside the `retainTokens` budget. The auto- @@ -369,7 +369,11 @@ export class BasicCompactService extends CompactService { * carries it in front of the history (`EpochHeader.messagePrefix`) even * though it is not derived history — omitting it would under-estimate by * exactly the prefix and let a deployment at the window edge skip - * compaction, then ship an over-window request. Compaction itself can only + * compaction, then ship an over-window request. The loop composes the + * prefix BEFORE the pre-step seam and hands it through, so the gate sees + * this instance's actual prefix (never a previous instance's logged one — + * a resumed/forked instance whose contributor grew is gated on the grown + * value from its very first step). Compaction itself can only * shrink HISTORY: a prefix that alone approaches the window is a * configuration error no compactor fixes. * @@ -395,13 +399,14 @@ export class BasicCompactService extends CompactService { override async compactIfNeeded( agent: Agent, fullSystemPrompt: string, + sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise { const session = agent.session const threshold = Math.floor(this.config.contextWindow * this.config.thresholdRatio) let result: CompactionResult | null = null for (let attempt = 0; attempt <= this.config.compactionRetries; attempt++) { - const totalTokens = this.estimatePressure(session, fullSystemPrompt) + const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix) if (totalTokens < threshold) return result const range = this._compactableRange(session) @@ -415,7 +420,7 @@ export class BasicCompactService extends CompactService { result = await this.compactRegion(session, range.start, range.end, agent, signal) } - const totalTokens = this.estimatePressure(session, fullSystemPrompt) + const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix) if (totalTokens < threshold) return result throw new Error( @@ -425,19 +430,16 @@ export class BasicCompactService extends CompactService { } /** - * Estimated token pressure of the NEXT request: the logged session prefix - * (`EpochHeader.messagePrefix` from the header fold — request-only messages - * the loop sends in front of the derived history), the derived history, and - * the system prompt. The fold is exact from the loop instance's second - * request on (and from a resumed instance's first — the previous instance - * logged its prefix); it is absent only before a fresh session's first - * request, where the history is a single prompt and compaction is moot. + * Estimated token pressure of the NEXT request: the session prefix + * (`EpochHeader.messagePrefix` — request-only messages the loop sends in + * front of the derived history, composed before the pre-step seam and + * handed to the gate), the derived history, and the system prompt. * @param session - the session whose next request is being estimated. * @param fullSystemPrompt - the assembled system prompt (counts toward pressure). + * @param sessionPrefix - the instance's composed session prefix (counts toward pressure). * @returns the estimated token total the next request will carry. */ - estimatePressure(session: Session, fullSystemPrompt: string): number { - const sessionPrefix = session.requestHeader()?.messagePrefix ?? [] + estimatePressure(session: Session, fullSystemPrompt: string, sessionPrefix: readonly Message[]): number { return this.estimateTokens([...sessionPrefix, ...session.deriveMessages()], fullSystemPrompt) } diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index b58e50f4c3..e40f079c6b 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -557,27 +557,22 @@ describe('BasicCompactService.compactIfNeeded', () => { expect(result!.shadowedSeqs.length).toBeGreaterThan(0) }) - it('counts the logged session prefix toward pressure (every request carries it in front of the history)', async () => { + it('counts the session prefix toward pressure (every request carries it in front of the history)', async () => { const svc = createTestService({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 10 }) const session = multiTurnSession(3, 1) // 6 derived messages ≈ 84 estimated tokens — under the 100 threshold alone expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull() - // The loop records the composed agent/session-prefix product on the - // request header; it rides every request, so pressure must include it. - session.append('request/header', { - header: { - config: { model: 'm' }, - messagePrefix: [ - { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] }, - { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] }, - ], - }, - reason: 'initial', - }) - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) + // The loop composes the agent/session-prefix product before the pre-step + // seam and hands it to the gate; it rides every request, so pressure must + // include it — the same history now crosses the threshold. + const sessionPrefix: Message[] = [ + { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] }, + { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] }, + ] + const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL, sessionPrefix) expect(result).not.toBeNull() // The prefix itself is NOT history: compaction shadowed surface nodes only. - expect(session.requestHeader()?.messagePrefix).toHaveLength(2) + expect(sessionPrefix).toHaveLength(2) }) it('returns the first compaction result when a zero-retry pass converges after the loop', async () => { @@ -1005,8 +1000,9 @@ function compactIfNeeded( fullSystemPrompt: string, model: string, signal: AbortSignal, + sessionPrefix: readonly Message[] = [], ) { - return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, signal) + return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, sessionPrefix, signal) } function compactRegion( @@ -1174,7 +1170,7 @@ describe('BasicCompactService.summarize (real ctx.llm.stream)', () => { describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => { /** Fire the agent/pre-step serial checkpoint as the loop does. */ function firePreStep(ctx: Context, agent: Agent, step: number, fullSystemPrompt: string): Promise { - return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, SIGNAL) + return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, [], SIGNAL) } it('compacts (mutating the surface) when over threshold', async () => { @@ -1276,7 +1272,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => const session = multiTurnSession(5, 1) const agent = stubAgent(session, 'agent-model') - await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL) + await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL) expect(adapter.lastOptions?.model).toBe('routed-model') expect(session.events.some(e => e.type === 'compact/summary')).toBe(true) @@ -1415,7 +1411,7 @@ describe('BasicCompactService edge cases', () => { const session = multiTurnSession(4, 1) const agent = stubAgent(session, 'test-model') - await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL) + await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL) expect(session.events.some(e => e.type === 'compact/summary')).toBe(true) // The surface was mutated; the head message is the framed summary checkpoint. expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'SUMMARY' }) @@ -1495,7 +1491,7 @@ describe('BasicCompactService edge cases', () => { const agent = stubAgent(session, 'test-model') const before = session.surface.nodes.length - await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL) + await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL) // The failure was swallowed; the surface is untouched and a warning logged. expect(session.surface.nodes.length).toBe(before) expect(session.events.some(e => e.type === 'compact/summary')).toBe(false) @@ -1512,7 +1508,7 @@ describe('BasicCompactService edge cases', () => { const agent = stubAgent(session, 'test-model') const bigSystem = 'x'.repeat(900) // ceil(900/4)=225 > threshold 200 - await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, SIGNAL) + await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, [], SIGNAL) expect(session.events.some(e => e.type === 'compact/start')).toBe(false) expect(svc.summarizeCalls.length).toBe(0) }) diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts index cc190ccd87..8ba121a43f 100644 --- a/packages/compact/compact/src/index.ts +++ b/packages/compact/compact/src/index.ts @@ -22,6 +22,7 @@ */ import { Context, Service } from 'cordis' +import type { Message } from '@deepseek-ai/dsh-llm' import type { Session } from '@deepseek-ai/dsh-session' import type { CompactionResult } from './types.ts' @@ -68,16 +69,20 @@ export abstract class CompactService extends Service { /** * Check token pressure and compact if the conversation is too large. * - * Estimates the current surface-derived history size (including the system - * prompt), and if it exceeds the backend's threshold, compacts an older range + * Estimates the NEXT request's size — the session prefix, the + * surface-derived history, and the system prompt — and if it exceeds the + * backend's threshold, compacts an older range * via {@link compactRegion}, keeping recent context intact. Returns `null` * when no compaction is needed. * * Scope and guarantees a backend MUST honor: - * - **Surface-derived history only.** The decision is made against the history - * derived from the session surface — the only thing compaction can act on. - * Non-surface context injected downstream (into the request `messages` by a - * later listener) is out of this accounting by construction. + * - **Compaction acts on surface-derived history only**, but the ESTIMATE + * counts everything the request carries: the loop composes the session + * prefix before the pre-step seam fires and hands it here, so the gate + * sees the prefix this instance will actually send (`EpochHeader.messagePrefix` + * — request-only, never derived history). Non-surface context injected + * downstream (into the request `messages` by a later listener) is out of + * this accounting by construction. * - **Head-anchored, best-effort.** Auto-compaction consolidates from the * surface HEAD up to a balanced tool-pairing cutoff, so a prior head * checkpoint is @@ -88,10 +93,14 @@ export abstract class CompactService extends Service { * - **Single-unit overflow is out of scope.** If a single retained unit (one * closed step, or a large free node such as a pasted `user/message`) ALONE * exceeds the budget, compaction cannot help and the call may go out - * over-budget. Bounding an individual unit's size is a separate concern. + * over-budget. Bounding an individual unit's size is a separate concern — + * as is a session prefix that alone approaches the window (a + * configuration error no compactor fixes: compaction cannot shrink the + * prefix). * * @param agent - agent context owning the session surface and model options. * @param fullSystemPrompt - assembled system prompt, counted toward the estimate. + * @param sessionPrefix - the instance's composed session prefix, counted toward the estimate. * @param signal - cancellation signal. A backend summarizing via * `ctx.llm.stream()` MUST forward this into the call's `GenerateOptions.signal` * so an abort/dispose tears down the in-flight summarization rather than @@ -101,6 +110,7 @@ export abstract class CompactService extends Service { abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, + sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise diff --git a/packages/compact/compact/tests/compact.spec.ts b/packages/compact/compact/tests/compact.spec.ts index 93c4e806ce..c4daa8cc5a 100644 --- a/packages/compact/compact/tests/compact.spec.ts +++ b/packages/compact/compact/tests/compact.spec.ts @@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' import { CompactService } from '@deepseek-ai/dsh-compact' import type { CompactionResult } from '@deepseek-ai/dsh-compact' +import type { Message } from '@deepseek-ai/dsh-llm' import { Session, SessionId } from '@deepseek-ai/dsh-session' import type { CompactAgentContext } from '@deepseek-ai/dsh-compact' @@ -18,6 +19,7 @@ class StubCompactService extends CompactService { override async compactIfNeeded( _agent: CompactAgentContext, _fullSystemPrompt: string, + _sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise { this.lastSignal = signal @@ -78,7 +80,7 @@ describe('CompactService seam', () => { const ctx = new Context() const svc = new StubCompactService(ctx) const session = new Session(SessionId('s')) - expect(await svc.compactIfNeeded(stubAgent(session), '', new AbortController().signal)).toBeNull() + expect(await svc.compactIfNeeded(stubAgent(session), '', [], new AbortController().signal)).toBeNull() }) it('compact/* events merge into SessionEventMap and are log-only', async () => { @@ -107,7 +109,7 @@ describe('CompactService seam', () => { await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), controller.signal) expect(svc.lastSignal).toBe(controller.signal) - await svc.compactIfNeeded(stubAgent(session), '', controller.signal) + await svc.compactIfNeeded(stubAgent(session), '', [], controller.signal) expect(svc.lastSignal).toBe(controller.signal) }) }) diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index d4c1c50466..2af8ad29f6 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -55,12 +55,13 @@ forever: STEP loop: drain steering assembly = systemPrompt.assemble({agent}) ⟵ renderPrompt(assembly) IS the full prompt - await serial agent/pre-step ⟵ surface mutation (compaction) outside the step + prefix ??= waterfall agent/session-prefix ⟵ once per instance (first step): frozen + session prefix; on the header, never history + await serial agent/pre-step(…, prefix) ⟵ surface mutation (compaction) outside the step; + pressure gates see the prefix the request carries boundary = session.deriveMessages() ⟵ reconstruction boundary: same sync frame, session('step/start') strictly before step/start config = waterfall agent/request ⟵ frozen seed; return a replacement to switch - prefix ??= waterfall agent/session-prefix ⟵ once per instance (first request): frozen - session prefix; on the header, never history session('request/header'[-delta]) ⟵ the header event this request owes the log stream llm.stream(freeze({header..., messages: prefix+boundary})) → session('assistant/chunk') message = waterfall agent/step-result diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index 753da50db7..31ebb61380 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -157,13 +157,14 @@ export interface LoopHandle { * drain steering → session('steering/message') ⟵ catches late steering * assembly = ctx.systemPrompt.assemble({agent}) ⟵ waterfall system-prompt/assemble; renderPrompt * (persona section + {{variables}}) IS the full prompt - * await ctx.serial('agent/pre-step') ⟵ surface mutation (compaction) OUTSIDE the step + * prefix ??= waterfall agent/session-prefix ⟵ once per loop instance (first step): frozen + * session prefix; logged on the header, never + * session history + * await ctx.serial('agent/pre-step', …, prefix) ⟵ surface mutation (compaction) OUTSIDE the step; + * pressure gates see the prefix the request carries * boundary = session.deriveMessages() ⟵ the reconstruction boundary: snapshot in the * session('step/start') same sync frame, strictly before step/start * config = waterfall agent/request(config) ⟵ frozen seed; a returned replacement switches - * prefix ??= waterfall agent/session-prefix ⟵ once per loop instance (first request): - * frozen session prefix; logged on the header, - * never session history * session('request/header'|'request/header-delta') ⟵ the header event this request owes the * log (initial/resume anchor, delta, fallback) * req = freeze({header..., messages: prefix+boundary, sessionId, signal}) @@ -475,6 +476,41 @@ async function runTurn( break } + // Compose the session prefix ONCE per loop instance, lazily before the + // instance's first pre-step: request-only messages placed in front of + // the ENTIRE derived history on every request this instance sends. It + // MUST precede the pre-step seam so compaction gates on THIS instance's + // prefix — reading a previous instance's logged prefix would let a + // resumed/forked instance whose contributor grew skip compaction and + // ship an over-window first request. The result is deep-cloned + // (decoupled from listener-held references), deep-frozen, and cached on + // the transmission bookkeeping, so reuse is structural — the prefix + // cannot change mid-session and the provider prefix cache holds by + // construction (resume = a new instance = a recompose, anchored by its + // 'resume' snapshot). The prefix is not session history — the header + // event in runStep is its only durable record + // (EpochHeader.messagePrefix). The frozen empty seed serves both the + // listener chain and the no-listener fallback: a contribution is a + // RETURNED extension of `await next()`, never an in-place push. This + // runs OUTSIDE the step, before the boundary snapshot: a composing + // listener's session append lands before the boundary and joins the + // CURRENT request. + if (transmission.sessionPrefix === undefined) { + const emptyPrefix: Message[] = deepFreeze([]) + transmission.sessionPrefix = deepFreeze(structuredClone(await ctx.waterfall( + 'agent/session-prefix', agent, emptyPrefix, abort.signal, + () => Promise.resolve(emptyPrefix), + ))) + } + + // Interruption landing during prefix composition: mirror the assembly + // window above — drop the about-to-start step without running the seam. + if (handle.isCancelled() || handle.isDisposed()) { + handle.setAbort(undefined) + reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } + break + } + // Pre-step surface-mutation checkpoint (compaction), fired OUTSIDE the // step: after `turn/start` (and the prior step's close) but before // `step/start`, so a compaction's log-only `compact/*` records and its @@ -485,8 +521,10 @@ async function runTurn( // concurrent listeners cannot interleave their `session.append`s. A // throwing listener escapes to the outer catch, which closes the (not-yet- // open) step as a no-op and ends the turn via failTurn — a broken - // pre-step plugin ends the turn, not the loop. - await ctx.serial('agent/pre-step', agent, turn, step, fullSystemPrompt, abort.signal) + // pre-step plugin ends the turn, not the loop. The composed session + // prefix rides along so token-pressure listeners count everything the + // request will actually carry. + await ctx.serial('agent/pre-step', agent, turn, step, fullSystemPrompt, transmission.sessionPrefix, abort.signal) // Interruption landing during the pre-step seam: do not open an empty step. if (handle.isCancelled() || handle.isDisposed()) { @@ -722,27 +760,10 @@ async function runStep( throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`) } - // Compose the session prefix ONCE per loop instance, lazily on its first - // request-building step: request-only messages placed in front of the - // ENTIRE derived history on every request this instance sends. The result - // is deep-cloned (decoupled from listener-held references), deep-frozen, - // and cached on the transmission bookkeeping, so reuse is structural — the - // prefix cannot change mid-session and the provider prefix cache holds by - // construction (resume = a new instance = a recompose, anchored by its - // 'resume' snapshot). The prefix is not session history — the header event - // below is its only durable record (EpochHeader.messagePrefix), which - // keeps the request a pure function of the log. The frozen empty seed - // serves both the listener chain and the no-listener fallback: a - // contribution is a RETURNED extension of `await next()`, never an - // in-place push. - if (transmission.sessionPrefix === undefined) { - const emptyPrefix: Message[] = deepFreeze([]) - transmission.sessionPrefix = deepFreeze(structuredClone(await ctx.waterfall( - 'agent/session-prefix', agent, emptyPrefix, signal, - () => Promise.resolve(emptyPrefix), - ))) - } - const sessionPrefix = transmission.sessionPrefix + // The session prefix was composed (once per instance) before this step's + // pre-step seam — the caller guarantees it, so the cache is always set here. + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- runTurn composes the prefix before every runStep call + const sessionPrefix = transmission.sessionPrefix! // The request header (the log's request/header* vocabulary): canonical form, // recorded before dispatch so the log always explains the request — diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 0e77f0bcbf..4b3be6e1c1 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -166,6 +166,69 @@ describe('Agent.cancel()', () => { expect(reasons.length).toBe(2) }) + it('cancel from inside the agent/session-prefix waterfall drops the step (prefix-composition window)', async () => { + const adapter = new MockAdapter([textResponse('should not stream')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + // Prefix composition runs before the pre-step seam on the instance's first + // step; a cancel landing inside it must drop the about-to-start step + // without running the seam or the model. + let streamed = false + ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true }) + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => { + agent.cancel('from prefix composition') + return next() + }) + + const reasons: TurnEndReason[] = [] + ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) }) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + expect(streamed).toBe(false) + expect(reasons).toEqual([{ kind: 'aborted', reason: 'from prefix composition' }]) + }) + + it('disposal from inside the agent/session-prefix waterfall ends the turn disposed (prefix-composition window)', async () => { + const adapter = new MockAdapter([textResponse('should not stream')]) + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + ctx.llm.registerAdapter(['mock'], adapter) + + const handle = ctx.agents.create({ + agentId: AgentId('a-dispose-prefix'), + sessionId: SessionId('dispose-prefix-session'), + agentOptions: { model: 'mock' }, + }) + const agent = handle.agent as ReactLoopAgent + + let disposalDone: Promise | undefined + let streamed = false + ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true }) + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => { + disposalDone = handle.dispose() + return next() + }) + + send(agent, 'go') + await new Promise(resolve => setTimeout(resolve, 0)) + await disposalDone + await agent.done + + // No step opened, no model call ran, and the turn closed disposed. + expect(streamed).toBe(false) + expect(adapter.requests).toHaveLength(0) + const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) + }) + it('cancel from a synchronous turn/start session-event listener drops the step (step-start window)', async () => { const adapter = new MockAdapter([textResponse('should not stream')]) const ctx = await harness(adapter) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index d97710e6d6..bab2ae6ea1 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -352,6 +352,33 @@ describe('agent/session-prefix', () => { expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] }) }) + it('composes before the first pre-step and hands the prefix to the seam (pressure gates see the real value)', async () => { + const adapter = new MockAdapter([textResponse('ok')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'opener' }] } + const order: string[] = [] + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { + order.push('compose') + return [reminder, ...await next()] + }) + const seen: (readonly Message[])[] = [] + ctx.on('agent/pre-step', (_agent, _turn, _step, _system, sessionPrefix) => { + order.push('pre-step') + seen.push(sessionPrefix) + }) + + send(agent, 'hi') + await waitForIdle(ctx, agent) + + // Composition precedes the pre-step seam, and the seam receives THIS + // instance's composed prefix — a token-pressure gate (compaction) counts + // what the request will actually carry, never a stale logged prefix. + expect(order).toEqual(['compose', 'pre-step']) + expect(seen[0]).toEqual([reminder]) + }) + it('the canonical prepend pattern composes contributions in registration order', async () => { const adapter = new MockAdapter([textResponse('ok')]) const ctx = await harness(adapter) diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 8a811048c6..8ad204c579 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -43,9 +43,9 @@ Turn and step boundaries are NOT mirrored as `agent/*` emits: a consumer that ne - `agent/session-start` (emit) — fired once before the first turn; a listener seeds context via `agent.inject()` (it cannot veto startup). - `agent/prompt-submit` — decide what happens to one drained queued message before it becomes a `user/message`: `PromptDecision` = `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (drop it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`). Maps onto Claude Code's `UserPromptSubmit`. -- `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step. +- `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step; carries the assembled system prompt and the instance's composed session prefix so a token-pressure gate counts everything the request will carry. - `agent/request` — shape the call config before the model call: a frozen `LlmCallConfig` seed in, a replacement out (model switching, sampling overrides). Content is not shapeable here — every request is a pure function of the session log ([reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)); the loop logs whatever config the request actually uses as a `request/header*` event -- `agent/session-prefix` — compose the session prefix: request-only messages placed in front of the ENTIRE derived history on every request. Fired ONCE per loop instance, lazily on its first request; the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the anchoring `request/header` snapshot, and reused verbatim afterwards — the prefix cannot change mid-session, so the provider prefix cache holds by construction (resume = a new instance = a recompose, attributably anchored by its `'resume'` snapshot). The home for session-stable openers that must not become durable history (a skills catalog, an AGENTS.md digest); `deriveMessages()` never returns it. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, `tools/post-execute` `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter +- `agent/session-prefix` — compose the session prefix: request-only messages placed in front of the ENTIRE derived history on every request. Fired ONCE per loop instance, lazily before its first pre-step (so pressure gates see this instance's real prefix, never a previous instance's logged one); the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the anchoring `request/header` snapshot, and reused verbatim afterwards — the prefix cannot change mid-session, so the provider prefix cache holds by construction (resume = a new instance = a recompose, attributably anchored by its `'resume'` snapshot). The home for session-stable openers that must not become durable history (a skills catalog, an AGENTS.md digest); `deriveMessages()` never returns it. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, `tools/post-execute` `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter - `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records) - `agent/turn-continuation` — override the continue/stop decision via `ContinuationDecision` = `{action:'stop'}` or `{action:'continue', reason?}` (a `continue` `reason` is recorded as next-step steering in the same turn — the typed `/goal` pattern). Force-continue `/loop`, force-stop budget guard. diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 9121fe87bb..f17c666286 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -333,21 +333,28 @@ declare module 'cordis' { * value; this event is typed and documented as `void`, so listeners must not * return a semantic veto value. `fullSystemPrompt` is the assembled prompt a * listener needs to measure pressure (the system prompt counts toward the - * budget). `signal` cancels any in-flight work a listener starts (e.g. a + * budget), and `sessionPrefix` is the instance's composed + * {@link agent/session-prefix} product for the same reason — every request + * carries it in front of the derived history, and it is composed BEFORE + * this seam fires precisely so a pressure gate counts the prefix the + * request will actually send (never a stale logged one). `signal` cancels + * any in-flight work a listener starts (e.g. a * summarization model call). * @param agent - the agent about to open the step. * @param turn - the already-open turn this step belongs to. * @param step - the number of the step about to start. * @param fullSystemPrompt - the assembled prompt, for measuring token pressure. + * @param sessionPrefix - the instance's frozen session prefix, for the same measurement. * @param signal - aborts in-flight listener work when the turn is torn down. * @mode serial */ - // TODO: `fullSystemPrompt` is a smell on a generic per-step seam — compaction - // is its only consumer, so a wide event carries a string just one listener + // TODO: `fullSystemPrompt`/`sessionPrefix` are a smell on a generic + // per-step seam — compaction + // is their only consumer, so a wide event carries payloads just one listener // reads. Revisit if no second consumer appears: e.g. hand listeners a lazy // prompt provider, or move token-pressure measurement behind a // compaction-specific seam instead of the shared pre-step checkpoint. - 'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal): Promise | void + 'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise | void /** * Waterfall: decide what happens to ONE drained queued message before it * becomes a `user/message` — allow (optionally rewriting the prompt bytes or @@ -389,13 +396,18 @@ declare module 'cordis' { * Waterfall: compose the SESSION PREFIX — request-only messages placed in * front of the ENTIRE derived history (directly after the provider's * system slot) on every request this loop instance sends. Fired ONCE per - * loop instance, lazily on its first request-building step; the composed + * loop instance, lazily before its first step's {@link agent/pre-step} + * seam — BEFORE the pre-step so a token-pressure gate (compaction) counts + * the prefix this instance will actually send, never a previous + * instance's logged one. The composed * result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the * instance's anchoring `'initial'`/`'resume'` header snapshot, and reused * verbatim for every subsequent request — never recomputed mid-session, * so the provider prefix cache holds by construction (a process restart * or `ctx.agents.resume()` is a new instance: it recomposes, and any - * drift lands attributably on the `'resume'` snapshot). + * drift lands attributably on the `'resume'` snapshot). Composition runs + * outside the step, before the boundary snapshot: a composing listener's + * session append joins the CURRENT request's derived history. * * This is the home for session-stable openers the model must always see * but that must NOT become durable history — a skills catalog, an From 9c133c644d3dec868be27a3ce01ecc0debd2e283 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 21:45:10 +0800 Subject: [PATCH 061/119] test(bash-local): wait for process readiness --- .../bash/bash-local/tests/executor.spec.ts | 4 ++-- packages/bash/bash-local/tests/run.spec.ts | 19 ++++++++++++++++--- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts index ce89b2a0ae..db25575484 100644 --- a/packages/bash/bash-local/tests/executor.spec.ts +++ b/packages/bash/bash-local/tests/executor.spec.ts @@ -90,8 +90,8 @@ describe('LocalBashExecutor.run', () => { it('kill escalation uses the configured graceMs (a TERM-trapping task dies by SIGKILL)', async () => { const { bash } = await setup() // setup pins graceMs: 200 via config - const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; sleep 60' })) - await new Promise(resolve => setTimeout(resolve, 100)) + const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo ready; while :; do sleep 60 & wait $!; done' })) + await readUntil(bash, task.id, 'ready\n') bash.kill(task.id) await task.done expect(task.signal).toBe('SIGKILL') diff --git a/packages/bash/bash-local/tests/run.spec.ts b/packages/bash/bash-local/tests/run.spec.ts index d2888e2fee..4f06fefadc 100644 --- a/packages/bash/bash-local/tests/run.spec.ts +++ b/packages/bash/bash-local/tests/run.spec.ts @@ -56,6 +56,20 @@ async function waitForStdout(running: RunningBash, expected: string, timeoutMs = throw new Error(`stdout did not include ${JSON.stringify(expected)} after ${timeoutMs}ms`) } +async function waitForPidFile(path: string, timeoutMs = 5_000): Promise { + const deadline = Date.now() + timeoutMs + while (Date.now() < deadline) { + try { + const pid = Number(readFileSync(path, 'utf8').trim()) + if (Number.isSafeInteger(pid) && pid > 0) return pid + } catch { + // The child shell has not written the pid file yet. + } + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`pid file ${path} was not written after ${timeoutMs}ms`) +} + describe('runBash', () => { it('captures stdout on success', async () => { const result = await runBash(spec('echo hello')).done @@ -107,7 +121,7 @@ describe('runBash', () => { }) it('escalates to SIGKILL when SIGTERM is trapped', async () => { - const running = runBash(spec('trap \'\' TERM; echo ready; sleep 60', { graceMs: 200 })) + const running = runBash(spec('trap \'\' TERM; echo ready; while :; do sleep 60 & wait $!; done', { graceMs: 200 })) await waitForStdout(running, 'ready\n') running.kill() const result = await running.done @@ -119,8 +133,7 @@ describe('runBash', () => { // group must take the sleep down with bash. const pidFile = join(spillDir, `grandchild-${Date.now()}.pid`) const running = runBash(spec(`sleep 60 & echo $! > ${pidFile}; wait`)) - await new Promise(resolve => setTimeout(resolve, 300)) - const grandchild = Number(readFileSync(pidFile, 'utf8').trim()) + const grandchild = await waitForPidFile(pidFile) expect(grandchild).toBeGreaterThan(0) running.kill() From 959a3c3a8b2198a78ad47f7a0d023ed7ac92d84d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 21:46:03 +0800 Subject: [PATCH 062/119] fix(agent-loop): discard an interrupted prefix composition instead of caching it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A cancel/dispose landing inside the first agent/session-prefix waterfall used to commit the listener chain's return value to the instance cache before the interruption check dropped the turn; an abort-aware listener's degraded fallback would then ship on every later request of the instance. The commit now happens only after the composition survives the interruption check — the cache only ever holds a fully composed prefix, and the next turn recomposes under a live signal. --- docs/cordis-catalog/events.md | 10 +++--- docs/event-producer-consumer.md | 8 ++--- packages/core/agent-loop/src/loop.ts | 27 +++++++++----- packages/core/agent-loop/tests/cancel.spec.ts | 36 ++++++++++++++++++- packages/core/agent/src/types.ts | 6 +++- 5 files changed, 67 insertions(+), 20 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 8b820168b3..cd7bb30e29 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -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:472`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:476`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -101,7 +101,7 @@ Source: [`packages/core/agent/src/types.ts:394`](../../packages/core/agent/src/t ### `agent/session-prefix` — waterfall -Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider's system slot) on every request this loop instance sends. Fired ONCE per loop instance, lazily before its first step's agent/pre-step seam — BEFORE the pre-step so a token-pressure gate (compaction) counts the prefix this instance will actually send, never a previous instance's logged one. The composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the instance's anchoring `'initial'`/`'resume'` header snapshot, and reused verbatim for every subsequent request — never recomputed mid-session, so the provider prefix cache holds by construction (a process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` snapshot). Composition runs outside the step, before the boundary snapshot: a composing listener's session append joins the CURRENT request's derived history. +Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider's system slot) on every request this loop instance sends. Fired ONCE per loop instance, lazily before its first step's agent/pre-step seam — BEFORE the pre-step so a token-pressure gate (compaction) counts the prefix this instance will actually send, never a previous instance's logged one. The composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the instance's anchoring `'initial'`/`'resume'` header snapshot, and reused verbatim for every subsequent request — never recomputed mid-session, so the provider prefix cache holds by construction (a process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` snapshot). Composition runs outside the step, before the boundary snapshot: a composing listener's session append joins the CURRENT request's derived history. A composition interrupted by a cancel/dispose landing inside the waterfall is discarded — never cached, logged, or sent — and the next turn recomposes under a live signal, so an abort-aware listener's degraded fallback cannot leak into later requests. This is the home for session-stable openers the model must always see but that must NOT become durable history — a skills catalog, an AGENTS.md digest, a workspace baseline: `Session.deriveMessages()` never returns the prefix, and the header events are its only durable record, so the request stays reconstructable from the log. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, a `tools/post-execute` decision's `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter. @@ -113,7 +113,7 @@ The seed is a frozen empty list; a contributing listener returns a NEW array — Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:437`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:441`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -149,7 +149,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:447`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:451`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -161,7 +161,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:460`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:464`](../../packages/core/agent/src/types.ts) ## `fs/*` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 19a2d4b1c0..a3c9cef433 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -9,16 +9,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac | --- | --- | --- | --- | --- | | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:472`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:476`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:357`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) | | `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:370`](../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/queued` | `emit` | [`packages/core/agent/src/types.ts:290`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:394`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:437`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:441`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:305`](../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:281`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:447`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:460`](../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/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:451`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:464`](../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) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../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:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index 31ebb61380..33ddee8f64 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -497,18 +497,27 @@ async function runTurn( // CURRENT request. if (transmission.sessionPrefix === undefined) { const emptyPrefix: Message[] = deepFreeze([]) - transmission.sessionPrefix = deepFreeze(structuredClone(await ctx.waterfall( + const composed = await ctx.waterfall( 'agent/session-prefix', agent, emptyPrefix, abort.signal, () => Promise.resolve(emptyPrefix), - ))) - } + ) - // Interruption landing during prefix composition: mirror the assembly - // window above — drop the about-to-start step without running the seam. - if (handle.isCancelled() || handle.isDisposed()) { - handle.setAbort(undefined) - reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } - break + // Interruption landing during prefix composition: mirror the assembly + // window above — drop the about-to-start step without running the + // seam, and DISCARD the composition instead of caching it. An + // abort-aware listener may have returned a degraded fallback under + // the firing signal; committing it would ship a prefix no request + // ever used (and no header ever logged) on this instance's next real + // request. The next turn recomposes under a live signal — the cache + // only ever holds a fully composed prefix. The cache-hit path needs + // no such check: nothing awaits between the assembly check above and + // the pre-step seam. + if (handle.isCancelled() || handle.isDisposed()) { + handle.setAbort(undefined) + reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } + break + } + transmission.sessionPrefix = deepFreeze(structuredClone(composed)) } // Pre-step surface-mutation checkpoint (compaction), fired OUTSIDE the diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 4b3be6e1c1..63a75447ca 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -12,7 +12,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import LlmService from '@deepseek-ai/dsh-llm' +import LlmService, { type Message } from '@deepseek-ai/dsh-llm' import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' @@ -229,6 +229,40 @@ describe('Agent.cancel()', () => { expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) }) + it('a cancel-interrupted prefix composition is discarded: the next send recomposes and ships the fresh prefix (stale-cache guard)', async () => { + const adapter = new MockAdapter([textResponse('reply')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) + + // The first composition is interrupted mid-waterfall and — like an + // abort-aware listener bailing on a firing signal — contributes nothing. + // Caching that degraded result would silently strip the prefix from every + // later request of this instance; the loop must discard it and recompose + // on the next send, and the SECOND composition's value must be what the + // wire and the header log carry. + const opener: Message = { role: 'user', content: [{ type: 'text', text: 'fresh opener' }] } + let compositions = 0 + ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { + compositions += 1 + if (compositions === 1) { + agent.cancel('mid-composition') + return next() + } + return [opener, ...await next()] + }) + + send(agent, 'dropped') + await waitForIdle(ctx, agent) + send(agent, 'real prompt') + await waitForIdle(ctx, agent) + + expect(compositions).toBe(2) + expect(adapter.requests).toHaveLength(1) + expect(adapter.requests[0]?.messages[0]).toEqual(opener) + const headerEvent = agent.session.events.find(e => e.type === 'request/header') + expect(headerEvent?.type === 'request/header' && headerEvent.data.header.messagePrefix).toEqual([opener]) + }) + it('cancel from a synchronous turn/start session-event listener drops the step (step-start window)', async () => { const adapter = new MockAdapter([textResponse('should not stream')]) const ctx = await harness(adapter) diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index f17c666286..2bde463be5 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -407,7 +407,11 @@ declare module 'cordis' { * or `ctx.agents.resume()` is a new instance: it recomposes, and any * drift lands attributably on the `'resume'` snapshot). Composition runs * outside the step, before the boundary snapshot: a composing listener's - * session append joins the CURRENT request's derived history. + * session append joins the CURRENT request's derived history. A + * composition interrupted by a cancel/dispose landing inside the + * waterfall is discarded — never cached, logged, or sent — and the next + * turn recomposes under a live signal, so an abort-aware listener's + * degraded fallback cannot leak into later requests. * * This is the home for session-stable openers the model must always see * but that must NOT become durable history — a skills catalog, an From 90547f283b2706d5c208e4528d09dd105b4082cf Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 21:56:28 +0800 Subject: [PATCH 063/119] fix: byte-exact value/error caps + write-callback contract (agent review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two [P1] review findings on the worker runtime: - maxValueBytes gated and sliced the rendered fallback by UTF-16 code units, so a multibyte string ("€€€€" under a 4-byte cap) crossed whole and a truncated multibyte rendering could still run ~3x over budget. New truncateUtf8Bytes cuts at code-point boundaries under a real byte budget; prepareValue's fallback and the host's forged-error-text bound both use it, and the VALUE_RENDER_SLACK comment drops its now-obsolete "sliced by characters" wrinkle. - The patched stream write dropped Node's optional encoding/callback arguments, so a program awaiting flush completion (write(chunk, resolve)) hung to the wall ceiling and misreported as a timeout. The shim now fires the callback asynchronously once the chunk is admitted — including for writes the exhausted budget drops. --- .../code-runtime-worker/src/bootstrap.ts | 45 ++++++++++++++-- .../code-runtime-worker/src/index.ts | 9 ++-- .../tests/bootstrap.spec.ts | 51 ++++++++++++++++++- .../code-runtime-worker/tests/runtime.spec.ts | 38 ++++++++++++++ 4 files changed, 132 insertions(+), 11 deletions(-) diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts index 62374ccaa0..f2e0d343f3 100644 --- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts +++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts @@ -98,6 +98,10 @@ export function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS) * Redirect a stream's `write` into the log buffer (the program-visible * `process.stdout`/`process.stderr` in the real worker), so raw writes land * in emission order alongside console output instead of racing down a pipe. + * The shim keeps Node's `write(chunk[, encoding][, callback])` contract: the + * callback fires asynchronously once the chunk is admitted (a program + * awaiting flush completion must complete, not sit until the wall timeout), + * even for writes the exhausted budget drops. * @param logs - the buffer captured writes are pushed into. * @param stream - the stream whose `write` slot is patched. * @param source - the log source the captured writes are attributed to. @@ -109,8 +113,14 @@ export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream, so // detached, so the unbound-method concern does not apply. // eslint-disable-next-line @typescript-eslint/unbound-method const original = stream.write - stream.write = (chunk: unknown): boolean => { + stream.write = (chunk: unknown, ...rest: unknown[]): boolean => { logs.push({ source, text: typeof chunk === 'string' ? chunk : String(chunk) }) + // Node's optional-encoding shape: the callback is whichever of the next + // two positions holds a function (a non-function there is the encoding). + const callback = [rest[0], rest[1]].find( + (arg): arg is (error?: Error | null) => void => typeof arg === 'function', + ) + if (callback) queueMicrotask(() => { callback(null) }) return true } return () => { stream.write = original } @@ -119,6 +129,28 @@ export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream, so /** Bounded inspect options: deep enough to be useful, bounded so a pathological value cannot explode the rendering. */ const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const +/** + * The longest prefix of `text` whose UTF-8 encoding fits `maxBytes`, cut at + * a code-point boundary (never mid-surrogate-pair). The byte caps are BYTE + * caps — `String.prototype.slice` counts UTF-16 code units, up to 3× smaller + * than what a multibyte string actually costs across the boundary. + * @param text - the string to bound. + * @param maxBytes - the UTF-8 byte budget the prefix must fit. + * @returns the prefix (all of `text` when it already fits). + */ +export function truncateUtf8Bytes(text: string, maxBytes: number): string { + if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text + let bytes = 0 + let end = 0 + for (const char of text) { + const cost = Buffer.byteLength(char, 'utf8') + if (bytes + cost > maxBytes) break + bytes += cost + end += char.length + } + return text.slice(0, end) +} + /** * Prepare the program's completion value for the done message: a value whose * MEASURED cross-boundary size fits `maxValueBytes` crosses raw — exact @@ -126,9 +158,10 @@ const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 * everything else, so a huge container whose BOUNDED inspect rendering * happens to be small cannot smuggle itself past the cap. Anything else * (non-cloneable, or oversized) is REPLACED by its bounded `util.inspect` - * rendering, truncated with an in-band marker — the seam contract's "a - * non-transferable value is replaced by a string rendering", extended to - * oversized ones so a huge return cannot flood the host. + * rendering, byte-truncated ({@link truncateUtf8Bytes}) with an in-band + * marker — the seam contract's "a non-transferable value is replaced by a + * string rendering", extended to oversized ones so a huge return cannot + * flood the host. * @param value - the program's completion value. * @param maxValueBytes - the byte cap for the value. * @returns the done-message fragment: `{}` for `undefined`, else `{ value }`. @@ -150,7 +183,9 @@ export function prepareValue(value: unknown, maxValueBytes: number): { value?: u if (size !== undefined && size <= maxValueBytes) return { value } } const rendered = typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS) - const capped = rendered.length > maxValueBytes ? `${rendered.slice(0, maxValueBytes)}… [truncated]` : rendered + const capped = Buffer.byteLength(rendered, 'utf8') > maxValueBytes + ? `${truncateUtf8Bytes(rendered, maxValueBytes)}… [truncated]` + : rendered return { value: capped } } diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts index 7749fb0318..f78f06cb0b 100644 --- a/packages/code-runtime/code-runtime-worker/src/index.ts +++ b/packages/code-runtime/code-runtime-worker/src/index.ts @@ -18,7 +18,7 @@ import { Context } from 'cordis' import z from 'schemastery' import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime' import type { CodeBindingFunction, CodeLogEntry, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime' -import { prepareValue } from './bootstrap.ts' +import { prepareValue, truncateUtf8Bytes } from './bootstrap.ts' import { logTruncationMarker } from './protocol.ts' import type { ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts' @@ -166,9 +166,8 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined { /** * Headroom the host's value re-cap grants over `maxValueBytes`: exactly the * truncation suffix {@link prepareValue} appends, so a value the WORKER - * already capped passes through unchanged instead of being marked twice. - * (A multibyte rendering the worker sliced by characters can still exceed - * this and pick up a second marker — bounded and harmless.) + * already capped (byte-exact prefix + this marker) passes through unchanged + * instead of being marked twice. */ const VALUE_RENDER_SLACK = Buffer.byteLength('… [truncated]', 'utf8') @@ -357,7 +356,7 @@ export class WorkerCodeRuntime extends CodeRuntime { // unchanged (see VALUE_RENDER_SLACK); the error text is bounded too. finish({ ...prepareValue(message.value, this.config.maxValueBytes + VALUE_RENDER_SLACK), - ...message.error ? { error: { kind: 'exception' as const, message: message.error.message.slice(0, this.config.maxValueBytes) } } : {}, + ...message.error ? { error: { kind: 'exception' as const, message: truncateUtf8Bytes(message.error.message, this.config.maxValueBytes) } } : {}, }) } diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts index 685c152b10..e41f4455bb 100644 --- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts +++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' import { EventEmitter } from 'node:events' -import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, wireReplies } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts' +import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, truncateUtf8Bytes, wireReplies } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts' import type { BootstrapPort, PatchableStream, PendingCall } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts' import type { ReplyMessage, WorkerToHost } from '@deepseek-ai/dsh-code-runtime-worker/src/protocol.ts' import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime' @@ -90,6 +90,27 @@ describe('captureStreamWrites', () => { expect(seen[0]).toMatchObject({ source: 'stdout' }) expect(underlying).toBe('after') }) + + it('invokes the write callback asynchronously, in both optional-encoding shapes', async () => { + const buffer = new LogBuffer(1_000, () => {}) + const stream: PatchableStream = { write: () => true } + captureStreamWrites(buffer, stream, 'stdout') + const calls: (Error | null | undefined)[] = [] + stream.write('two-arg', (error?: Error | null) => calls.push(error)) + stream.write('three-arg', 'utf8', (error?: Error | null) => calls.push(error)) + // Node's contract: the callback fires after the write call returns. + expect(calls).toEqual([]) + await new Promise(resolve => stream.write('awaited flush', resolve)) + expect(calls).toEqual([null, null]) + }) + + it('still fires the callback for a write the exhausted budget drops', async () => { + const buffer = new LogBuffer(4, () => {}) + const stream: PatchableStream = { write: () => true } + captureStreamWrites(buffer, stream, 'stdout') + stream.write('this write overflows the budget and is dropped') + await new Promise(resolve => stream.write('also dropped', resolve)) + }) }) describe('prepareValue', () => { @@ -118,6 +139,34 @@ describe('prepareValue', () => { expect(typeof value).toBe('string') expect(value).toContain('more items') }) + + it('caps a multibyte string by UTF-8 bytes, not UTF-16 length', () => { + // 4 code units but 12 UTF-8 bytes: a length-counting cap would pass the + // full string through untruncated. + expect(prepareValue('€€€€', 4)).toEqual({ value: '€… [truncated]' }) + }) + + it('caps a multibyte rendering by UTF-8 bytes too', () => { + // Wire size (24-byte string inside an array) exceeds the cap, so the + // value crosses as its rendering — whose truncation must also be + // byte-exact: "[ '" (3 bytes) + two € (6 bytes) = 9; a third € would + // overflow the 10-byte budget. + expect(prepareValue(['€€€€€€€€'], 10)).toEqual({ value: "[ '€€… [truncated]" }) + }) +}) + +describe('truncateUtf8Bytes', () => { + it('returns a fitting string whole', () => { + expect(truncateUtf8Bytes('fits', 4)).toBe('fits') + }) + + it('cuts at a code-point boundary, never mid-surrogate-pair', () => { + // Each 😀 is one code point, two code units, four UTF-8 bytes: a 5-byte + // budget fits exactly one — and never leaves a lone surrogate behind. + const cut = truncateUtf8Bytes('😀😀', 5) + expect(cut).toBe('😀') + expect(Buffer.byteLength(truncateUtf8Bytes('😀😀', 3), 'utf8')).toBe(0) + }) }) describe('makeNamespaces', () => { diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts index 2d29dc143d..edc2bd1271 100644 --- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts +++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts @@ -221,6 +221,29 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => { expect(result.value).toBe(`${'y'.repeat(64)}… [truncated]`) }) + it('caps a multibyte return value by UTF-8 bytes, not string length', async () => { + // 4 code units, 12 UTF-8 bytes: a length-counting cap would let the full + // string cross. The worker's byte-exact capped rendering then passes the + // host re-cap unchanged (cap + marker is exactly the granted slack). + const { runtime } = await setup({ maxValueBytes: 4 }) + const result = await runtime.run({ program: 'return "€€€€"', bindings: [] }) + expect(result.value).toBe('€… [truncated]') + }) + + it('completes a program that awaits its write callback, capturing the chunk', async () => { + // Node's write(chunk[, encoding][, callback]) contract: dropping the + // callback would leave this promise pending until the wall ceiling and + // misreport a completed program as a timeout. + const { runtime } = await setup({ maxWallMs: 2_000 }) + const result = await runtime.run({ + program: 'await new Promise(resolve => process.stdout.write("flushed", resolve)); return "done"', + bindings: [], + }) + expect(result.error).toBeUndefined() + expect(result.value).toBe('done') + expect(result.logs).toContainEqual({ source: 'stdout', text: 'flushed' }) + }) + it('caps a huge container whose bounded rendering is small (wire size, not rendering, is what counts)', async () => { const { runtime } = await setup() const result = await runtime.run({ program: 'return new Array(50_000).fill(7)', bindings: [] }) @@ -340,6 +363,21 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => { expect(result.error).toEqual({ kind: 'exception', message: 'fake failure' }) }) + it('byte-bounds forged multibyte error text at the host', async () => { + // Forged error text bypasses the worker entirely; the host bound is a + // BYTE bound (two € = 6 bytes fit an 8-byte cap, a third would not). + const { runtime } = await setup({ maxValueBytes: 8 }) + const result = await runtime.run({ + program: ` + const { parentPort } = await import('node:worker_threads'); + parentPort.postMessage({ type: 'done', error: { message: '€'.repeat(1000) } }); + for (;;) {} + `, + bindings: [], + }) + expect(result.error).toEqual({ kind: 'exception', message: '€€' }) + }) + it('answers a binding whose resolution cannot be cloned with a failure reply', async () => { const { runtime } = await setup() const result = await runtime.run({ From 1b29273f12a1e3659d9792ee55bca5ce8e2198bf Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Wed, 8 Jul 2026 22:03:27 +0800 Subject: [PATCH 064/119] fix: reach quiescence even when the runtime rejects (agent review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [P1] review finding: the run-scoped abort + queue drain ran only after runtime.run() FULFILLED, so a backend that starts a binding call and then throws left the sub-dispatch running past run_code's settlement — its tool/code-dispatch event could append after the parent call returned, breaking the drain-before-return contract. The quiescence pair now lives in a finally around runtime.run(); the folded queue tail keeps the drain from masking the thrown error. Pinned by a test whose fake runtime fails mid-flight: pre-fix it returns in milliseconds with the slow tool still running. --- packages/core/tools/src/code-mode.ts | 38 +++++++++++++-------- packages/core/tools/tests/code-mode.spec.ts | 38 +++++++++++++++++++++ 2 files changed, 61 insertions(+), 15 deletions(-) diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index 970bb6e208..404364d57c 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -250,21 +250,29 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => } try { - const result = await runtime.run({ - program: args.code, - bindings: [{ global: 'tools', functions }], - signal: runController.signal, - }) - // Quiescence before returning: fire the run-scoped abort (cancelling - // an in-flight sub-dispatch, abandoning queued ones), then await the - // queue's drain — an aborted sub-call still settles and logs its - // event INSIDE the open turn; nothing can append after we return. - // `queue` is the FOLDED tail (every link swallows its rejection into - // undefined), so this await cannot itself reject — an abandoned - // queued call can never mask the runtime's own `result.error` below; - // rejections surface only on the per-call promises the program holds. - runController.abort('run_code settled') - await queue + let result: CodeRunResult + try { + result = await runtime.run({ + program: args.code, + bindings: [{ global: 'tools', functions }], + signal: runController.signal, + }) + } finally { + // Quiescence before returning, whether the runtime fulfilled or + // REJECTED (a backend that starts a binding call and then throws + // must not leak a live sub-dispatch past this settlement): fire + // the run-scoped abort (cancelling an in-flight sub-dispatch, + // abandoning queued ones), then await the queue's drain — an + // aborted sub-call still settles and logs its event INSIDE the + // open turn; nothing can append after we return. `queue` is the + // FOLDED tail (every link swallows its rejection into undefined), + // so this await cannot itself reject — an abandoned queued call + // can never mask the runtime's own failure, returned or thrown; + // rejections surface only on the per-call promises the program + // holds. + runController.abort('run_code settled') + await queue + } if (result.error) { const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.map(entry => entry.text).join('\n')}` : '' diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index 7cbceb5361..03afc260ee 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -385,6 +385,44 @@ describe('the run_code dispatch bridge', () => { expect(sawAbort).toBe(true) }) + it('a runtime that starts a binding call and then REJECTS still reaches quiescence before returning', async () => { + const { ctx, runtime } = await setup({ mode: 'code' }) + const { agent, events } = fakeAgent() + let sawAbort = false + let started!: () => void + const inFlight = new Promise((resolve) => { started = resolve }) + ctx.tools.register(defineTool({ + name: 'slow', + description: 'Slow tool observing its signal.', + parameters: { id: { type: 'string', required: true } }, + async execute(args, exec) { + started() + await new Promise((resolve) => { + const timer = setTimeout(resolve, 500) + exec.signal?.addEventListener('abort', () => { sawAbort = true; clearTimeout(timer); resolve() }, { once: true }) + }) + return [{ type: 'text' as const, text: args.id }] + }, + })) + runtime.behavior = async (request) => { + // Start a sub-dispatch, keep its rejection held, and fail the run once + // the tool is genuinely in flight — a seam error AFTER work has begun. + // The bridge's settlement still owes quiescence: without the finally, + // run_code would return now and the slow tool would finish (and log) + // afterwards. + request.bindings[0]!.functions.slow!({ id: 'orphan' }).catch(() => 'held') + await inFlight + throw new Error('backend exploded') + } + const result = await runCode(ctx, 'program', { agent }) + expect(result.isError).toBe(true) + expect((result.content[0] as { text: string }).text).toContain('backend exploded') + // Quiescence held: the in-flight sub-dispatch was aborted and its event + // logged INSIDE the run_code execution, not after it returned. + expect(sawAbort).toBe(true) + expect(events.filter(event => event.type === 'tool/code-dispatch').map(event => (event.data as { name: string }).name)).toEqual(['slow']) + }) + it('runs without an owning agent: dispatches work, event logging is skipped', async () => { const { ctx, runtime } = await setup({ mode: 'code' }) const calls = registerEcho(ctx) From fd1071392c484b97305bb3e2f7b0aabfe28dba4d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 8 Jul 2026 22:40:38 +0800 Subject: [PATCH 065/119] docs(compact): sync the compactIfNeeded prose signature with the sessionPrefix parameter The seam gained sessionPrefix between fullSystemPrompt and signal in 18d478bc, but the compact README member table and the compaction core-data-structures page still showed the 3-arg form and listed only agent/system/signal as what pre-step supplies. The generated service catalog was already correct; only these two prose homes drifted. --- docs/core-data-structures/compaction.md | 2 +- packages/compact/compact/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md index 78eb48d38e..2f402be57d 100644 --- a/docs/core-data-structures/compaction.md +++ b/docs/core-data-structures/compaction.md @@ -50,6 +50,6 @@ interface CompactionResult { ## The service -`CompactService` (`ctx.compact`, abstract — defined in [`packages/compact/compact/src/index.ts`](../../packages/compact/compact/src/index.ts)) declares two abstract methods: `compactIfNeeded(agent, fullSystemPrompt, signal)` checks token pressure and compacts an older range if the history is too large (returning `null` when nothing needs it), and `compactRegion(session, start, end, agent, signal?)` forcibly summarizes surface nodes `[start, end]` into a single replacement node. `compactIfNeeded`'s parameters are all required — the loop's `agent/pre-step` checkpoint supplies the agent, the assembled `fullSystemPrompt`, and the turn `signal`. A backend summarizing via `ctx.llm.stream()` must forward `signal` into the call's `GenerateOptions.signal`, so an abort or dispose tears down the in-flight summarization. The entire strategy — token estimation, retention policy, event sequencing, summarization — is a HOW decision owned by the implementation. +`CompactService` (`ctx.compact`, abstract — defined in [`packages/compact/compact/src/index.ts`](../../packages/compact/compact/src/index.ts)) declares two abstract methods: `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` checks token pressure and compacts an older range if the history is too large (returning `null` when nothing needs it), and `compactRegion(session, start, end, agent, signal?)` forcibly summarizes surface nodes `[start, end]` into a single replacement node. `compactIfNeeded`'s parameters are all required — the loop's `agent/pre-step` checkpoint supplies the agent, the assembled `fullSystemPrompt`, the instance's composed `sessionPrefix` (request-only messages the derived history omits, so the pressure estimate must count them), and the turn `signal`. A backend summarizing via `ctx.llm.stream()` must forward `signal` into the call's `GenerateOptions.signal`, so an abort or dispose tears down the in-flight summarization. The entire strategy — token estimation, retention policy, event sequencing, summarization — is a HOW decision owned by the implementation. Auto-compaction runs on the serial `agent/pre-step` loop seam (fired once per step, after `turn/start` and BEFORE the step opens and its request history is derived), not the `agent/request` waterfall: compaction mutates the session surface in place — with its log-only `compact/*` records landing cleanly outside any step — and the loop derives the request from the already-compacted surface. Retention is turn-agnostic — the only structural guard is tool-pairing balance (a compacted region's edges are balanced cuts on the surface, so it never splits a step's tool-calls from their results), so a single runaway turn that alone exceeds the window compacts its own early closed steps rather than being retained verbatim. The backend that ships this (`dsh-compact-basic`) documents the retention walk, summary shrink validation, bounded re-compaction, and the crash/recoverable failure taxonomy. diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md index 54bdcc7f4e..e817fcfb10 100644 --- a/packages/compact/compact/README.md +++ b/packages/compact/compact/README.md @@ -18,7 +18,7 @@ Both methods are **abstract** — the backend owns the entire strategy (token es | Member | Semantics | |---|---| -| `compactIfNeeded(agent, fullSystemPrompt, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. | +| `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, composed `sessionPrefix` (request-only messages every request carries but the derived history omits — the pressure estimate must count them), and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. | | `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. | `compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The session being compacted comes from the agent context; the turn that the `compact/*` events belong to is recoverable from the log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value. From 064d1c4ce16ce8184b99064c1656de9dfb8f0c88 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 00:38:21 +0800 Subject: [PATCH 066/119] docs: state advisory typing in the worker row (review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A reviewer read "TypeScript via host-side type-strip" and reasonably asked what typing buys if nothing checks it — the group README never said the annotations are advisory by design. The row now states it; the rationale stays in the RFC and the enforcement story (per-dispatch validateArgs) in the dsh-tools README. --- packages/code-runtime/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md index b98baa43e6..0310a57b1a 100644 --- a/packages/code-runtime/README.md +++ b/packages/code-runtime/README.md @@ -5,6 +5,6 @@ The code-execution capability seam (see [capability seams](../../docs/rfc/implem | Package | Role | ctx key | |---|---|---| | `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` | -| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip, port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` | +| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` | The interface lives at `code-runtime/code-runtime/`; the shipped backend at `code-runtime/code-runtime-worker/`. Backends differ by execution substrate (worker thread, process, container) and by source language — both readonly descriptors on the service — and register `ctx.codeRuntime` without touching the interface or its consumer; that split is what makes a hardened backend a drop-in later. From f2c333e51031c4db7719c12e71c8cc4dde32f8fe Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 9 Jul 2026 00:40:57 +0800 Subject: [PATCH 067/119] docs(rfc): record the session-prefix decision MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seam shipped without its own RFC — the reconstructable-requests RFC was amended with the mechanics, but the decision record (why a compose-once frozen prefix, and what the per-request before/after shape, a system-prompt section, a durable history opener, per-turn composition, and a dedicated session event each lost to) had no home. Implemented lifecycle, feature class, dated to the first commit of the work. --- docs/rfc/INDEX.md | 1 + .../feature/2026-07-07-session-prefix.md | 42 +++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 docs/rfc/implemented/feature/2026-07-07-session-prefix.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index b746e7e1f8..4d784ba3e5 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -62,6 +62,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 | | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 | | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 | +| [The session prefix — request-only messages in front of the derived history](implemented/feature/2026-07-07-session-prefix.md) | 2026-07-07 | | [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 | ### Simplification diff --git a/docs/rfc/implemented/feature/2026-07-07-session-prefix.md b/docs/rfc/implemented/feature/2026-07-07-session-prefix.md new file mode 100644 index 0000000000..6f81d12407 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-07-session-prefix.md @@ -0,0 +1,42 @@ +# RFC: The session prefix — request-only messages in front of the derived history + +Status: implemented + +## Problem + +A plugin often owns a session-stable opener the model must always see — a skills catalog, an AGENTS.md digest, a workspace baseline. Before this seam the harness offered two homes, and both are wrong for that content. The system prompt is one rendered string: message-shaped content (a user-role `` envelope, a multi-message primer) does not fit it, and providers weight conversation messages differently from system text. Durable history (`agent.inject()`, a `context/message` at session start) makes the opener permanent: every `deriveMessages()` consumer replays it, the compaction retention walk owns it, forks bake it in stale, and a resume cannot refresh it — a catalog captured at session birth outlives the world it described. + +The obvious third option — let a plugin edit the request's `messages` on the way out — is banned by [the reconstructable-requests RFC](../architecture/2026-07-05-reconstructable-requests.md): every loop-built request is a pure function of the session log, so whatever channel carries the opener must log exactly what it sends. What was missing was a request-only message channel with a durable record. + +## Decision + +`agent/session-prefix` is a waterfall on the agent event map ([`packages/core/agent/src/types.ts`](../../../../packages/core/agent/src/types.ts)): listeners receive a frozen empty seed and return an extension (the canonical contribution is a prepend, `[mine, ...await next()]`, which yields registration order on the wire). The loop ([`packages/core/agent-loop/src/loop.ts`](../../../../packages/core/agent-loop/src/loop.ts)) fires it once per loop instance, lazily before the instance's first `agent/pre-step`; the composed list is deep-cloned, deep-frozen, cached on the instance, and placed in front of the ENTIRE derived history — directly after the provider's system slot — on every request the instance sends ([wire order](../../../core-data-structures/core.md#the-request-envelope-llmcallconfig-and-the-logged-header)). + +Three properties carry the design: + +- **Request-only, header-logged.** `deriveMessages()` never returns the prefix; its one durable record is `EpochHeader.messagePrefix` on the instance's anchoring `request/header` snapshot — the channel the reconstructable-requests RFC already owns for the request's non-history half, so no new session event exists. The dev invariant ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)) recomputes `messagePrefix + boundary derivation` against every loop-built request; an unlogged prefix cannot reach the wire. +- **Frozen per instance.** Reuse is structural, not disciplined: the cached product cannot change mid-session, so the provider's prompt cache holds by construction and the prefix extends the cacheable region at zero marginal cost per step. A process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` header snapshot. This is the routing rule the seam creates: session-frozen openers ride the prefix; content that changes mid-session rides the append-only history channels (`agent.inject()`, a `tools/post-execute` decision's `additionalContext`, prompt-submit `additionalContext` — [the interception-seams RFC](2026-06-30-interception-seams.md)), each a durable `context/message` paid once and prefix-cached thereafter. +- **Composed before the pressure gate.** Composition precedes the instance's first `agent/pre-step`, and the seam hands the composed value through: `agent/pre-step` carries a `sessionPrefix` parameter and `CompactService.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` counts it in its token-pressure estimate — a gate reading the previous instance's folded prefix instead would under-gate a resumed or forked instance whose contributor grew, skipping compaction and shipping an over-window first request. A composition interrupted by a cancel/dispose landing inside the waterfall is discarded, never cached: an abort-aware listener's degraded fallback cannot leak into later requests, and the next turn recomposes under a live signal. + +Because composition runs before the boundary snapshot, a composing listener's session append joins the CURRENT request's derived history. Compaction structurally cannot touch the prefix (or the system prompt): it rewrites surface nodes, and header state never enters the surface. + +## Testing + +**Unit** — [interception.spec.ts](../../../../packages/core/agent-loop/tests/interception.spec.ts) pins compose-once across turns and steps (one composition, zero `request/header-delta`s), canonical prepend ordering, empty-prefix omission from the header, the frozen seed (in-place push throws), held-reference mutation immunity, and composition-precedes-pre-step with the seam receiving the composed value; [cancel.spec.ts](../../../../packages/core/agent-loop/tests/cancel.spec.ts) pins cancel/dispose landing inside the composition window and the discard-and-recompose stale-cache guard; dsh-session codec tests cover the `messagePrefix` fold/diff/apply arms (empty ≡ absent); dsh-invariants tests pin the `messagePrefix + derivation` equation; dsh-compact-basic tests pin that the pressure estimate counts the handed prefix. **Snapshot** — the acp-snapshot normalizer scrubs header prefixes to count-preserving `{{messagePrefix}}` tokens (unit-covered in dsh-acp-snapshot); header content itself is pinned per [the pinned-header scenario RFC](../testing/2026-07-06-pin-request-header-content-in-one-scenario.md), and the example tree loads no prefix contributor, so live goldens stay prefix-free. **e2e** — none prefix-specific: the seam is provider-independent and deterministic; the with-key cache measurement in [request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts) already proves the cacheable-prefix economics the design rests on. + +## Alternatives considered + +- **Per-request `before`/`after` slots recomputed every step** (the shape first proposed: a waterfall firing on every request, contributing frozen `before` messages ahead of the history and fresh `after` messages behind it) — rejected. A per-step `before` recompose invites silent drift — nothing anchors it to the log short of logging a header delta per step — and an `after` slot sits behind the growing history, so its tokens re-pay on every request and everything after it is uncacheable. Measured against the alternatives, every current update pattern is served cheaper by a durable append (paid once, cache-read thereafter), and the only content with no home was the session-stable opener — which wants freezing, not recomputation. +- **A system-prompt section** (`system-prompt/assemble`) — rejected for this content: the assembly renders to the single `system` string, so message-shaped openers do not fit, and the system prompt is deliberately re-assembled per step (with header deltas when it changes) while the opener wants instance-frozen semantics. +- **A durable history opener** (`inject()` at session start) — rejected: permanent history is the failure mode in the problem statement — replayed everywhere, compactable, stale across resumes. +- **Compose per turn instead of per instance** — rejected: a turn-boundary recompose either desyncs silently from the log or forces a header delta per change, and it busts the provider cache exactly as often as it fires; the legitimate refresh point is the instance boundary, where the `'resume'` snapshot already records drift attributably. +- **Compose lazily at the first request and let compaction read the folded header** (the shape as first merged) — superseded in review: the fold matches the live prefix only from the instance's second request on, so on a resumed/forked instance's first step the pressure gate read the PREVIOUS instance's prefix and could under-gate. Composing before the first pre-step and handing the live value through the seam makes the estimate exact at every step. +- **A dedicated session event carrying the prefix** — rejected: the header events are the request's non-history record by design; a second event would be a second home for the same fact and another codec to keep total. + +## Consequences + +- `agent/pre-step` and `CompactService.compactIfNeeded` carry a `sessionPrefix` parameter: every pre-step listener and compaction backend sees the real per-instance value (all in-repo implementations updated in the same change, per the pre-release stance). +- A contributor whose content changes mid-session is not re-read until the next instance — by design. A deployment needing mid-session catalog updates routes the change notice through the append-only history channels and pays one durable `context/message`. +- The dropped `after` slot leaves no request-only channel near the request tail; nothing in the repo needs one, and adding it back would re-open the every-step re-pay cost the design exists to avoid. +- The `request/header-delta` `messagePrefix` arm (whole-array replacement, empty array encoding transition to absence) exists for codec totality; the loop never exercises it, because the cached prefix cannot change within an instance. +- An empty composition is canonical absence: no-contributor deployments log no extra header bytes and their requests are the bare derivation. From 56091d5b5d126cc2b21b57fef93b299143db6f81 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 9 Jul 2026 00:40:13 +0800 Subject: [PATCH 068/119] fix review findings: keep ask-user opt-in for acp app --- docs/config-catalog.md | 2 +- docs/module-graph.md | 3 +-- .../rfc/implemented/feature/2026-06-25-ask-user-question.md | 2 +- examples/acp-agent/tests/snapshots/text-turn/session.jsonl | 2 +- packages/ui/acp-agent/README.md | 6 +++--- packages/ui/acp-agent/package.json | 2 -- packages/ui/acp-agent/src/index.ts | 2 -- packages/ui/acp-agent/tests/acp-agent.spec.ts | 4 ++-- pnpm-lock.yaml | 3 --- 9 files changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 54c3830761..da05f3c2bb 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -56,7 +56,7 @@ export interface Config { } ``` -Source: [`packages/ui/acp-agent/src/index.ts:51`](../packages/ui/acp-agent/src/index.ts) +Source: [`packages/ui/acp-agent/src/index.ts:50`](../packages/ui/acp-agent/src/index.ts) ## `@deepseek-ai/dsh-agent-core` diff --git a/docs/module-graph.md b/docs/module-graph.md index 140449870c..2cd5fafc20 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -213,7 +213,6 @@ flowchart TD pkg_acp_agent --> pkg_agent_core pkg_acp_agent --> pkg_app_boot pkg_acp_agent --> pkg_session_persistence_jsonl - pkg_acp_agent --> pkg_tool_ask_user pkg_acp_agent --> pkg_user_interaction pkg_stdio_agent --> pkg_agent pkg_stdio_agent --> pkg_agent_core @@ -275,5 +274,5 @@ flowchart TD | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | -| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`user-interaction`](../packages/core/user-interaction) | +| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`user-interaction`](../packages/core/user-interaction) | | [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`user-interaction`](../packages/core/user-interaction) | diff --git a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md index 04d183aa9c..bc041cabc3 100644 --- a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md +++ b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md @@ -42,7 +42,7 @@ ACP elicitation is currently marked unstable in the SDK. The fallback is still s The feature gives the model a powerful pause primitive, so prompt guidance matters. The tool description tells the model to ask concise questions and use options when possible. Product policy can later wrap `tools/execute` to restrict when the tool is allowed, but the loop should not special-case it. -`dsh-tool-ask-user` lives in `packages/ui` even though it is a tool, because it is a product-facing human-interaction affordance rather than providerless loop infrastructure. The core package remains only the abstract seam; `agent-core` does not load the tool. Front-door app packages such as `stdio-agent` and `acp-agent` opt into it alongside their UI provider. +`dsh-tool-ask-user` lives in `packages/ui` even though it is a tool, because it is a product-facing human-interaction affordance rather than providerless loop infrastructure. The core package remains only the abstract seam; `agent-core` does not load the tool. `stdio-agent` opts into it alongside its readline provider. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests. ## Testing diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index f717b9071f..2a71c46b18 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -2,7 +2,7 @@ {"type":"turn/start","seq":0,"time":1783279329596,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":1,"time":1783279329596,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":2,"time":1783279329598,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"ask_user_question","description":"Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.","parameters":{"type":"object","properties":{"questions":{"type":"array","description":"Questions to ask the user before continuing.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for this question; echoed in the answer."},"question":{"type":"string","description":"The specific question to ask the user."},"header":{"type":"string","description":"Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."},"options":{"type":"array","description":"Optional choices to show the user.","items":{"type":"object","properties":{"label":{"type":"string","description":"Short user-facing option label."},"description":{"type":"string","description":"One sentence explaining the tradeoff or impact."}},"required":["label"]}},"multi_select":{"type":"boolean","description":"Whether the user may select more than one option. Defaults to false."}},"required":["id","question"]}}},"required":["questions"]}},{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} {"type":"assistant/chunk","seq":4,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":5,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":6,"time":1783279330154,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/packages/ui/acp-agent/README.md b/packages/ui/acp-agent/README.md index 0e1554d0c6..ee3a995eaa 100644 --- a/packages/ui/acp-agent/README.md +++ b/packages/ui/acp-agent/README.md @@ -11,10 +11,10 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it | Plugin | Why | |---|---| | `@deepseek-ai/dsh-agent-core` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) | -| `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools | -| `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool | +| `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests | | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) | -| `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers | +| `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool | +| ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately | | ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../acp/README.md)) | | ~~`hmr`~~ | **omitted** — the editor owns the subprocess | diff --git a/packages/ui/acp-agent/package.json b/packages/ui/acp-agent/package.json index 215113461b..51eb0ea3b1 100644 --- a/packages/ui/acp-agent/package.json +++ b/packages/ui/acp-agent/package.json @@ -36,7 +36,6 @@ "@deepseek-ai/dsh-acp": "^0.0.1", "@deepseek-ai/dsh-agent-core": "^0.0.1", "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1", - "@deepseek-ai/dsh-tool-ask-user": "^0.0.1", "@deepseek-ai/dsh-user-interaction": "^0.0.1", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" @@ -49,7 +48,6 @@ "@deepseek-ai/dsh-agent-core": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", - "@deepseek-ai/dsh-tool-ask-user": "workspace:^", "@deepseek-ai/dsh-user-interaction": "workspace:^", "cordis": "^4.0.0-rc.6", "schemastery": "^3.17.0" diff --git a/packages/ui/acp-agent/src/index.ts b/packages/ui/acp-agent/src/index.ts index 58a4eddda5..18490ac668 100644 --- a/packages/ui/acp-agent/src/index.ts +++ b/packages/ui/acp-agent/src/index.ts @@ -36,7 +36,6 @@ import * as acp from '@deepseek-ai/dsh-acp' import * as agentCore from '@deepseek-ai/dsh-agent-core' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' import UserInteractionService from '@deepseek-ai/dsh-user-interaction' -import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user' export const name = 'acp-agent' @@ -82,7 +81,6 @@ export function apply(ctx: Context, config: Config): void { ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {}, }) ctx.plugin(UserInteractionService) - ctx.plugin(toolAskUser) ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' }) ctx.plugin(acp, { model: config.model }) } diff --git a/packages/ui/acp-agent/tests/acp-agent.spec.ts b/packages/ui/acp-agent/tests/acp-agent.spec.ts index 3207f584ff..6e2f202859 100644 --- a/packages/ui/acp-agent/tests/acp-agent.spec.ts +++ b/packages/ui/acp-agent/tests/acp-agent.spec.ts @@ -31,7 +31,7 @@ describe('dsh-acp-agent composition', () => { expect(ctx.get('sessionPersistence')).toBeDefined() expect(ctx.get('agentLoop')).toBeDefined() expect(ctx.get('userInteraction')).toBeDefined() - expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined() + expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined() // No pre-created agents — ACP session/new creates them on demand. expect(ctx.get('agents')!.list()).toHaveLength(0) await ctx.fiber.dispose() @@ -72,7 +72,7 @@ describe('dsh-acp-agent composition', () => { }) } const assembly = await ctx.get('systemPrompt')!.assemble() - expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question']) + expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha']) await ctx.fiber.dispose() }) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 84c798a18a..014cce1ae1 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -970,9 +970,6 @@ importers: '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../core/system-prompt - '@deepseek-ai/dsh-tool-ask-user': - specifier: workspace:^ - version: link:../tool-ask-user '@deepseek-ai/dsh-user-interaction': specifier: workspace:^ version: link:../../core/user-interaction From 7ccf31a59b5227d66a95b2d52932d68b59e2b702 Mon Sep 17 00:00:00 2001 From: pku-xht Date: Thu, 9 Jul 2026 10:20:42 +0800 Subject: [PATCH 069/119] fix review finding: root-portable rm-failure injection in the config-dir test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The best-effort-remove test provoked a real EACCES via a chmod-000 subtree, which only fails for unprivileged users — under root, recursive rm ignores permission bits, deleting the subtree: the existsSync assertion goes red and the swallow branch loses coverage, failing the per-file gate. The rejection is now injected deterministically at the node:fs/promises boundary (rm wrapped with a real-passthrough vi.fn; one test queues a single rejection), the fs-failure boundary being exactly the non-deterministic seam the testing policy sanctions mocking. Everything else in the suite stays on the real filesystem, and the swallow contract stays error-kind agnostic. --- packages/subagent/subagent-process/README.md | 2 +- .../tests/subagent-process.spec.ts | 39 +++++++++++-------- 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/packages/subagent/subagent-process/README.md b/packages/subagent/subagent-process/README.md index 597470f52a..e42bb4b611 100644 --- a/packages/subagent/subagent-process/README.md +++ b/packages/subagent/subagent-process/README.md @@ -37,4 +37,4 @@ A per-run isolated config directory for an external CLI child (the target of `CL ## Testing -`tests/subagent-process.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (including an rm-failure path proving `remove()` never rejects); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end. +`tests/subagent-process.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end. diff --git a/packages/subagent/subagent-process/tests/subagent-process.spec.ts b/packages/subagent/subagent-process/tests/subagent-process.spec.ts index c4828d8498..24f2a3a97d 100644 --- a/packages/subagent/subagent-process/tests/subagent-process.spec.ts +++ b/packages/subagent/subagent-process/tests/subagent-process.spec.ts @@ -1,7 +1,7 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { EventEmitter } from 'node:events' import { existsSync } from 'node:fs' -import { chmod, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises' +import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import type { ChildProcess } from 'node:child_process' @@ -15,13 +15,24 @@ import { waitForExit, } from '../src/index.ts' +// `rm` is wrapped (real-passthrough by default) so ONE test can inject a +// rejection deterministically. A real recursive-rm failure is not portably +// provokable — permission tricks (a chmod-000 subtree) fail only for +// unprivileged users and are ignored by root — so this is the fs boundary +// the testing policy sanctions mocking; everything else stays the real fs. +vi.mock('node:fs/promises', async (importOriginal) => { + const actual = await importOriginal() + return { ...actual, rm: vi.fn(actual.rm) } +}) + /** * Unit tests for the shared out-of-process machinery. The env scrub and the * isolated-config-dir helpers run against the REAL process env and REAL - * filesystem; the exit waits and the dispose ladder run against a scriptable - * fake child so each escalation tier's timing is driven deterministically - * (the ACP backend's suite exercises the same ladder against real - * subprocesses end to end). + * filesystem (one exception: the rm-failure path injects its rejection at the + * mocked fs boundary, see above); the exit waits and the dispose ladder run + * against a scriptable fake child so each escalation tier's timing is driven + * deterministically (the ACP backend's suite exercises the same ladder + * against real subprocesses end to end). */ /** What fells a scripted {@link FakeChild}. */ @@ -287,20 +298,16 @@ describe('createIsolatedConfigDir', () => { expect(existsSync(missing)).toBe(false) }) - it('remove() is best-effort: an rm failure resolves instead of rejecting', async () => { + it('remove() is best-effort: an rm rejection resolves instead of rejecting', async () => { const dir = await createIsolatedConfigDir('dsh-subagent-process-locked-') - const locked = join(dir.path, 'locked') - await mkdir(locked) - await writeFile(join(locked, 'entry'), 'x') - // An unreadable, unwritable non-empty subdir makes recursive rm fail - // (EACCES on readdir/unlink) for a non-root user. - await chmod(locked, 0o000) try { + // The swallow contract is error-kind agnostic; EACCES stands in for the + // family (EBUSY, a vanished mount, …) that best-effort must absorb. + vi.mocked(rm).mockRejectedValueOnce(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' })) await expect(dir.remove()).resolves.toBeUndefined() - // rm really did fail — the locked subtree is still there. - expect(existsSync(locked)).toBe(true) + // The injected rejection consumed the only rm call — nothing was deleted. + expect(existsSync(dir.path)).toBe(true) } finally { - await chmod(locked, 0o700) await rm(dir.path, { recursive: true, force: true }) } }) From 2471e2b2bb45d1f8f350571451feda04a4a8786d Mon Sep 17 00:00:00 2001 From: pku-xht Date: Thu, 9 Jul 2026 10:42:34 +0800 Subject: [PATCH 070/119] fix review finding: exitsWithin cleans up its listener and timer on both arms Each timed-out wait used to leave the once('exit') listener from its inner waitForExit attached to the child; the dispose ladder accumulates at most a couple, but in a shared library a caller polling exitsWithin in a loop would pile listeners onto one child (MaxListenersExceededWarning at 11) and retain their closures. The race now owns its wiring: the timeout arm removes the exit listener, the exit arm clears the (still unref'ed) grace timer, and an already-exited child short-circuits true without attaching anything. Tests pin listenerCount('exit') === 0 after every outcome. --- packages/subagent/subagent-process/README.md | 2 +- .../subagent/subagent-process/src/index.ts | 24 ++++++++++++++----- .../tests/subagent-process.spec.ts | 12 ++++++++++ 3 files changed, 31 insertions(+), 7 deletions(-) diff --git a/packages/subagent/subagent-process/README.md b/packages/subagent/subagent-process/README.md index e42bb4b611..e6c8e10a96 100644 --- a/packages/subagent/subagent-process/README.md +++ b/packages/subagent/subagent-process/README.md @@ -16,7 +16,7 @@ Spawn-failure capture: a promise that resolves (never rejects) with the child's ### `waitForExit(child)` / `exitsWithin(child, ms)` -Exit waits over a `ChildProcess`: resolve once the child exits by any code or signal (immediately if it is already gone), or race that against a timer (`true` = exited in time; the pending timer is `unref()`ed so a grace window never keeps the parent's event loop alive). +Exit waits over a `ChildProcess`: resolve once the child exits by any code or signal (immediately if it is already gone), or race that against a timer (`true` = exited in time). The race cleans up after itself on both outcomes — the pending timer is `unref()`ed and cleared on exit, the exit listener removed on timeout — so repeated calls (the dispose ladder's tiers, a poll loop) never accumulate listeners on the child. ### `disposeChildProcess(child, graces)` diff --git a/packages/subagent/subagent-process/src/index.ts b/packages/subagent/subagent-process/src/index.ts index b54681d3c7..219ed6b083 100644 --- a/packages/subagent/subagent-process/src/index.ts +++ b/packages/subagent/subagent-process/src/index.ts @@ -78,17 +78,29 @@ export function waitForExit(child: ChildProcess): Promise { } /** - * Race the child's exit against a timer. + * Race the child's exit against a timer. Neither outcome leaves anything + * behind on the child: the exit listener is removed on timeout and the timer + * is cleared on exit, so repeated calls (the dispose ladder's tiers, a poll + * loop) never accumulate listeners. * @param child - the child process to watch. * @param ms - the wait window in milliseconds. - * @returns `true` if the child exits within `ms`, `false` on timeout. + * @returns `true` if the child exits within `ms` (immediately if it is + * already gone), `false` on timeout. */ export function exitsWithin(child: ChildProcess, ms: number): Promise { - return Promise.race([ - waitForExit(child).then(() => true), + if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true) + return new Promise((resolve) => { + const onExit = (): void => { + clearTimeout(timer) + resolve(true) + } // `.unref()` so a pending grace timer never keeps the parent's loop alive. - new Promise(resolve => setTimeout(() => { resolve(false) }, ms).unref()), - ]) + const timer = setTimeout(() => { + child.removeListener('exit', onExit) + resolve(false) + }, ms).unref() + child.once('exit', onExit) + }) } /** diff --git a/packages/subagent/subagent-process/tests/subagent-process.spec.ts b/packages/subagent/subagent-process/tests/subagent-process.spec.ts index 24f2a3a97d..d23f075284 100644 --- a/packages/subagent/subagent-process/tests/subagent-process.spec.ts +++ b/packages/subagent/subagent-process/tests/subagent-process.spec.ts @@ -181,15 +181,27 @@ describe('waitForExit / exitsWithin', () => { expect(fake.signalCode).toBe('SIGTERM') }) + it('exitsWithin resolves true immediately for an already-exited child (no listener attached)', async () => { + const fake = new FakeChild() + fake.exitCode = 0 + await expect(exitsWithin(asChild(fake), 1000)).resolves.toBe(true) + expect(fake.listenerCount('exit')).toBe(0) + }) + it('exitsWithin resolves true when the child exits inside the window', async () => { const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 }) fake.kill('SIGTERM') await expect(exitsWithin(asChild(fake), 1000)).resolves.toBe(true) + // The once-listener fired and the grace timer was cleared — nothing lingers. + expect(fake.listenerCount('exit')).toBe(0) }) it('exitsWithin resolves false on timeout for a child that never exits', async () => { const fake = new FakeChild() // nothing short of SIGKILL fells it; no signal sent await expect(exitsWithin(asChild(fake), 20)).resolves.toBe(false) + // The timeout arm removed its exit listener: repeated waits (a poll loop, + // the ladder's tiers) never accumulate listeners on the same child. + expect(fake.listenerCount('exit')).toBe(0) }) }) From a11000030a14dd382548839894ba49b0568ab801 Mon Sep 17 00:00:00 2001 From: pku-xht Date: Thu, 9 Jul 2026 10:42:41 +0800 Subject: [PATCH 071/119] docs(subagent-acp): point the env-scrub section at its one home MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The scrub pattern and layering semantics live in the dsh-subagent-process README (the fact's home since the extraction); the ACP section restated them in full — two prose copies drift word by word until they disagree (the one-home-per-fact rule in docs/AGENTS.md). The section now links the library and keeps only the backend's own story: which credential enters via config.env and why. --- packages/subagent/subagent-acp/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md index 81bf886067..2cc330aefd 100644 --- a/packages/subagent/subagent-acp/README.md +++ b/packages/subagent/subagent-acp/README.md @@ -57,7 +57,7 @@ A spawn/transport/RPC failure resolves `error` (or `aborted` if a cancel was req ## Environment scrub -Credential-shaped ambient vars (`/KEY|SECRET|TOKEN/i`) are NOT forwarded to the child by default — the parent harness's own secrets must not leak into a spawned process implicitly. The child's OWN credentials are supplied explicitly via `config.env`, layered AFTER the scrub, so an intended `DEEPSEEK_API_KEY` survives while an incidental `AWS_SECRET_ACCESS_KEY` does not. +The child env is built by [`buildChildEnv` from `@deepseek-ai/dsh-subagent-process`](../subagent-process/README.md) — the ambient env minus credential-shaped vars, with `config.env` layered on top after the scrub; the pattern and full semantics live there. For this backend that means the parent harness's own secrets never leak into the spawned agent implicitly, while the child's OWN `DEEPSEEK_API_KEY` is supplied deliberately via `config.env` and survives. ## Testing From 7db9a6c78039b0324acbc89a0df1679f975944fd Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 9 Jul 2026 11:20:17 +0800 Subject: [PATCH 072/119] fix review findings: document ask-user recommendation convention --- packages/ui/tool-ask-user/README.md | 2 +- packages/ui/tool-ask-user/src/index.ts | 2 +- .../tool-ask-user/tests/tool-ask-user.spec.ts | 31 +++++++++++++++++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/packages/ui/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md index 11f35c5129..10d4a082ba 100644 --- a/packages/ui/tool-ask-user/README.md +++ b/packages/ui/tool-ask-user/README.md @@ -10,7 +10,7 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo - `id` — required stable id on each question, echoed in the answer. - `question` — required question text for each question. - `header` — optional short heading. -- `options` — optional choices with `label` and `description`. +- `options` — optional choices with `label` and `description`. If recommending a choice, put it first and append `(Recommended)` to that label. - `multi_select` — whether that question may return more than one selected option. The tool calls `ctx.userInteraction.ask()` and returns JSON text shaped as `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices. diff --git a/packages/ui/tool-ask-user/src/index.ts b/packages/ui/tool-ask-user/src/index.ts index 6048f66808..2591b28ddd 100644 --- a/packages/ui/tool-ask-user/src/index.ts +++ b/packages/ui/tool-ask-user/src/index.ts @@ -36,7 +36,7 @@ export function apply(ctx: Context): void { }, options: { type: 'array', - description: 'Optional choices to show the user.', + description: 'Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label.', items: { type: 'object', properties: { diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts index b0fdd2cc41..ceff7df388 100644 --- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts +++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts @@ -99,6 +99,37 @@ describe('ask_user_question tool', () => { }]) }) + it('passes recommended option labels through without adding schema fields', async () => { + const ctx = await setup() + const seen: AskUserQuestionRequest[] = [] + ctx.userInteraction.registerProvider({ + async ask(request) { + seen.push(request) + return { answers: [{ id: 'pkg', selected: ['pnpm (Recommended)'] }] } + }, + }) + + await ctx.tools.execute({ + callId: CallId('ask-recommended'), + name: 'ask_user_question', + arguments: { + questions: [{ + id: 'pkg', + question: 'Which package manager should I use?', + options: [ + { label: 'pnpm (Recommended)' }, + { label: 'npm' }, + ], + }], + }, + }) + + expect(seen[0]?.questions[0]?.options).toEqual([ + { label: 'pnpm (Recommended)' }, + { label: 'npm' }, + ]) + }) + it('projects custom answers and multi-select choices', async () => { const ctx = await setup() ctx.userInteraction.registerProvider({ From 0009d1369330a71e252146afc2e2643fdde08848 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 9 Jul 2026 11:21:27 +0800 Subject: [PATCH 073/119] docs: refresh tool catalog --- docs/tool-catalog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 1a6425b36d..5b9bebeaf7 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -52,7 +52,7 @@ Ask the user a concise question when you need confirmation, a choice, or missing }, "options": { "type": "array", - "description": "Optional choices to show the user.", + "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.", "items": { "type": "object", "properties": { From 1be9baeb7bc9def875be4fe97397755d15685f27 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:44:10 +0800 Subject: [PATCH 074/119] =?UTF-8?q?feat:=20add=20demo:acp-code=20=E2=80=94?= =?UTF-8?q?=20the=20ACP=20demo=20in=20Code=20Mode?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Boots the acp-agent example through the existing code-mode.cordis.yml overlay (tool surface collapses to run_code + the generated TypeScript SDK, dispatching through the worker-thread runtime), mirroring how demo:code relates to demo:repl on the stdio side. The overlay header and both READMEs now name the demo as a consumer. Smoke: the server answers an ACP initialize handshake with a clean frame on stdout. --- examples/README.md | 2 +- examples/acp-agent/README.md | 3 ++- examples/acp-agent/code-mode.cordis.yml | 11 ++++++----- package.json | 1 + 4 files changed, 10 insertions(+), 7 deletions(-) diff --git a/examples/README.md b/examples/README.md index 1b9cdf080e..d42144ec9a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -29,4 +29,4 @@ Run with: `pnpm run demo:code` (needs `DEEPSEEK_API_KEY`). See [code-agent/READM An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. -Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`). See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design. +Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`); `pnpm run demo:acp-code` boots the same server in Code Mode via the `code-mode.cordis.yml` overlay. See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design. diff --git a/examples/acp-agent/README.md b/examples/acp-agent/README.md index a1f6e818ab..b00604a056 100644 --- a/examples/acp-agent/README.md +++ b/examples/acp-agent/README.md @@ -4,9 +4,10 @@ The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)* ```sh pnpm run demo:acp # needs DEEPSEEK_API_KEY (repo-root .env or env) +pnpm run demo:acp-code # the same server in Code Mode: one wire tool, run_code ``` -This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC. +This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC. `demo:acp-code` boots the same tree through the [`code-mode.cordis.yml`](code-mode.cordis.yml) overlay — the tool surface collapses to `run_code` + the generated TypeScript SDK, dispatching through the worker-thread code runtime (see the [dsh-tools Code Mode section](../../packages/core/tools/README.md#code-mode)). ## stdout is the protocol diff --git a/examples/acp-agent/code-mode.cordis.yml b/examples/acp-agent/code-mode.cordis.yml index 244cad9209..0dfbd73d26 100644 --- a/examples/acp-agent/code-mode.cordis.yml +++ b/examples/acp-agent/code-mode.cordis.yml @@ -1,11 +1,12 @@ -# Code Mode RECORD overlay: the live acp-agent tree (./cordis.yml) with two +# Code Mode overlay: the live acp-agent tree (./cordis.yml) with two # load-time patches — the app entry's config gains `tools: { mode: code }` # (the registry offers exactly one wire tool, run_code, plus the generated # TypeScript SDK prompt section) and the worker-thread code runtime joins the -# tree as `ctx.codeRuntime`. The dsh-acp-agent bin boots this file when the -# snapshot harness records the code-mode scenarios; DSH_SNAPSHOT=replay swaps -# it for the sibling code-mode.cordis.snapshot.yml. A config patch REPLACES -# the entry's whole config, so the base entry's fields are restated verbatim. +# tree as `ctx.codeRuntime`. The dsh-acp-agent bin boots this file for +# `pnpm run demo:acp-code` and when the snapshot harness records the +# code-mode scenarios; DSH_SNAPSHOT=replay swaps it for the sibling +# code-mode.cordis.snapshot.yml. A config patch REPLACES the entry's whole +# config, so the base entry's fields are restated verbatim. - id: base name: '@cordisjs/plugin-include' config: diff --git a/package.json b/package.json index 4fce3dad57..4ed429f1d0 100644 --- a/package.json +++ b/package.json @@ -65,6 +65,7 @@ "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", "demo:code": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/code-agent/cordis.yml", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", + "demo:acp-code": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/code-mode.cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, "devDependencies": { From bc7da642d4cb4770a31571c042ece8bac0b5d6d3 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 12:16:37 +0800 Subject: [PATCH 075/119] feat: fold the Code Mode demos into demo:code-mode with a UI argument MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Code Mode is the point; the UI is just the surface it happens to wear. demo:code and demo:acp-code collapse into one dispatcher (scripts/demo-code-mode.mjs): `pnpm run demo:code-mode [repl|acp]` — repl (default) boots the stdio REPL over examples/code-agent, acp serves examples/acp-agent's code-mode overlay; each UI runs the exact node invocation its standalone script ran, and an unknown argument fails loud with usage. All nine references across READMEs, the RFC, the overlay header, and the keyless-smoke comment renamed. Smoked all three paths: usage exit 2, ACP initialize handshake, REPL boot + EOF. --- .../feature/2026-06-15-code-mode.md | 2 +- examples/README.md | 4 +-- examples/acp-agent/README.md | 4 +-- examples/acp-agent/code-mode.cordis.yml | 2 +- examples/code-agent/README.md | 2 +- .../code-agent/tests/keyless-smoke.e2e.ts | 2 +- package.json | 3 +-- packages/core/tools/README.md | 2 +- scripts/demo-code-mode.mjs | 27 +++++++++++++++++++ 9 files changed, 37 insertions(+), 11 deletions(-) create mode 100644 scripts/demo-code-mode.mjs diff --git a/docs/rfc/implemented/feature/2026-06-15-code-mode.md b/docs/rfc/implemented/feature/2026-06-15-code-mode.md index 2f643b432e..5ce9d784b9 100644 --- a/docs/rfc/implemented/feature/2026-06-15-code-mode.md +++ b/docs/rfc/implemented/feature/2026-06-15-code-mode.md @@ -90,7 +90,7 @@ What exists now: - **The seam**: `packages/code-runtime/` — `@deepseek-ai/dsh-code-runtime` (abstract `CodeRuntime`, the vocabulary above, `ctx.codeRuntime`) and `@deepseek-ai/dsh-code-runtime-worker` (the worker-thread backend, every cap a validated config field). Rows in the service map, capability-seams graph, config catalog, and cordis catalog. - **The registry surface**: `ToolRegistry`'s first config (`mode`), the mode-aware wire contribution, the `tools:sdk` section, `jsonSchemaToTs`/`renderToolsSdk` (exported), `run_code` + the dispatch bridge + `CodeRunFailedError`, and the `tool/code-dispatch` log event (declaration-merged into `SessionEventMap`, regenerated into the persistence catalog; `run_code` in the tool catalog). -- **The composed surface**: the `tools` config forwards through `agent-core` and both app packages (`stdio-agent`, `acp-agent`); `examples/code-agent` + `demo:code` run the worker runtime under `mode: 'code'`; the adding-a-tool cookbook states that a registered tool is reachable from programs for free, and the tool-pipeline doc shows sub-dispatches re-entering both waterfalls. +- **The composed surface**: the `tools` config forwards through `agent-core` and both app packages (`stdio-agent`, `acp-agent`); `examples/code-agent` + `demo:code-mode` run the worker runtime under `mode: 'code'`; the adding-a-tool cookbook states that a registered tool is reachable from programs for free, and the tool-pipeline doc shows sub-dispatches re-entering both waterfalls. - **Interactions inherited by deployments**: a `toolOrder` naming native tools rejects every assembly under `'code'` (update or drop the order config when switching modes); sub-call `additionalContext` is dropped by the bridge (a plural context channel is deferred until a real hook needs it through Code Mode); sub-dispatch stays serialized until tools can declare concurrency safety — the same metadata the native parallel-dispatch TODO waits on. ## Testing diff --git a/examples/README.md b/examples/README.md index d42144ec9a..3027d01f0a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -23,10 +23,10 @@ Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a The coding agent flipped to **Code Mode**: the worker-thread code runtime is loaded and the tool registry runs `mode: code`, so the model gets exactly one wire tool — `run_code` — plus a generated TypeScript SDK section, and composes bash/read/write/edit/todo_write by writing a program whose output it curates. -Run with: `pnpm run demo:code` (needs `DEEPSEEK_API_KEY`). See [code-agent/README.md](code-agent/README.md) for what to try and how it differs from coding-agent. +Run with: `pnpm run demo:code-mode` (needs `DEEPSEEK_API_KEY`; the REPL is the default UI — `acp` as the argument serves the acp-agent example's Code Mode overlay instead). See [code-agent/README.md](code-agent/README.md) for what to try and how it differs from coding-agent. ## acp-agent An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. -Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`); `pnpm run demo:acp-code` boots the same server in Code Mode via the `code-mode.cordis.yml` overlay. See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design. +Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`); `pnpm run demo:code-mode acp` boots the same server in Code Mode via the `code-mode.cordis.yml` overlay. See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design. diff --git a/examples/acp-agent/README.md b/examples/acp-agent/README.md index b00604a056..5b3c936651 100644 --- a/examples/acp-agent/README.md +++ b/examples/acp-agent/README.md @@ -4,10 +4,10 @@ The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)* ```sh pnpm run demo:acp # needs DEEPSEEK_API_KEY (repo-root .env or env) -pnpm run demo:acp-code # the same server in Code Mode: one wire tool, run_code +pnpm run demo:code-mode acp # the same server in Code Mode: one wire tool, run_code ``` -This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC. `demo:acp-code` boots the same tree through the [`code-mode.cordis.yml`](code-mode.cordis.yml) overlay — the tool surface collapses to `run_code` + the generated TypeScript SDK, dispatching through the worker-thread code runtime (see the [dsh-tools Code Mode section](../../packages/core/tools/README.md#code-mode)). +This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC. `demo:code-mode acp` boots the same tree through the [`code-mode.cordis.yml`](code-mode.cordis.yml) overlay — the tool surface collapses to `run_code` + the generated TypeScript SDK, dispatching through the worker-thread code runtime (see the [dsh-tools Code Mode section](../../packages/core/tools/README.md#code-mode)). ## stdout is the protocol diff --git a/examples/acp-agent/code-mode.cordis.yml b/examples/acp-agent/code-mode.cordis.yml index 0dfbd73d26..d46e490494 100644 --- a/examples/acp-agent/code-mode.cordis.yml +++ b/examples/acp-agent/code-mode.cordis.yml @@ -3,7 +3,7 @@ # (the registry offers exactly one wire tool, run_code, plus the generated # TypeScript SDK prompt section) and the worker-thread code runtime joins the # tree as `ctx.codeRuntime`. The dsh-acp-agent bin boots this file for -# `pnpm run demo:acp-code` and when the snapshot harness records the +# `pnpm run demo:code-mode acp` and when the snapshot harness records the # code-mode scenarios; DSH_SNAPSHOT=replay swaps it for the sibling # code-mode.cordis.snapshot.yml. A config patch REPLACES the entry's whole # config, so the base entry's fields are restated verbatim. diff --git a/examples/code-agent/README.md b/examples/code-agent/README.md index 9b6619c0b3..6e08a883a3 100644 --- a/examples/code-agent/README.md +++ b/examples/code-agent/README.md @@ -3,7 +3,7 @@ The [Code Mode](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) form of the coding agent: instead of one native tool call per step, the model is offered exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK section declaring every other registered tool (`bash`, `read`, `write`, `edit`, `todo_write`). The model composes tools by writing a program; the program runs in a fresh worker thread (`@deepseek-ai/dsh-code-runtime-worker`), its tool calls bridge back through the ordinary `tools/pre-execute`/`post-execute` pipeline one at a time, each is logged as a `tool/code-dispatch` session event, and ONLY what the program prints or returns re-enters the model's context. ```sh -pnpm run demo:code # needs DEEPSEEK_API_KEY (repo-root .env works) +pnpm run demo:code-mode # needs DEEPSEEK_API_KEY (repo-root .env works) ``` Try a task that spans several tool calls, e.g.: diff --git a/examples/code-agent/tests/keyless-smoke.e2e.ts b/examples/code-agent/tests/keyless-smoke.e2e.ts index 4b7a150e99..d5913e48d5 100644 --- a/examples/code-agent/tests/keyless-smoke.e2e.ts +++ b/examples/code-agent/tests/keyless-smoke.e2e.ts @@ -42,7 +42,7 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> { return new Promise((resolve, reject) => { const proc = spawn( process.execPath, - // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:code). + // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:code-mode). ['--expose-internals', '--import', tsxLoader, binScript, configPath], { cwd, diff --git a/package.json b/package.json index 4ed429f1d0..b906964b1e 100644 --- a/package.json +++ b/package.json @@ -63,9 +63,8 @@ "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", - "demo:code": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/code-agent/cordis.yml", + "demo:code-mode": "node scripts/demo-code-mode.mjs", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", - "demo:acp-code": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/code-mode.cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, "devDependencies": { diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 7525fb8fd6..c0c7cfe437 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -133,7 +133,7 @@ Under `mode: code` (or `both`) the registry turns the tool surface into a progra - **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 the logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes the underlying `ctx.tools.execute()` calls one at a time in submission order — the tool contract carries no concurrency-safety metadata yet), gated by `tools/pre-execute`/`tools/post-execute` like any native call (a deny reaches the program as a binding rejection), and logged as one `tool/code-dispatch` session event (log-only: `deriveMessages()` never surfaces it) with the deterministic sub-id `:code:`. A failed sub-call REJECTS the program-side promise with the tool's error text — real code error handling, no bespoke envelope. A sub-call's `additionalContext` is deliberately DROPPED (no safe outlet mid-run without breaking tool-call/result adjacency; deferred until a real hook needs it through Code Mode). - **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. -The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free — under `code`, the assembled tool list is exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code` ([examples/code-agent](../../../examples/code-agent/README.md)). +The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free — under `code`, the assembled tool list is exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code-mode` ([examples/code-agent](../../../examples/code-agent/README.md)); `pnpm run demo:code-mode acp` serves the same mode over ACP instead of the REPL. ### What is NOT here (TODO) diff --git a/scripts/demo-code-mode.mjs b/scripts/demo-code-mode.mjs new file mode 100644 index 0000000000..465e5f2982 --- /dev/null +++ b/scripts/demo-code-mode.mjs @@ -0,0 +1,27 @@ +/** + * Boot the Code Mode demo under the UI named on the command line: + * `pnpm run demo:code-mode [repl|acp]`, default `repl`. Code Mode is the + * point — the UI is just the surface it happens to wear: `repl` starts the + * stdio REPL over examples/code-agent, `acp` starts the ACP server over + * examples/acp-agent's code-mode overlay. Both need DEEPSEEK_API_KEY + * (repo-root .env works). Anything else on the command line is a + * misconfiguration and fails loud with usage. + */ +import { spawn } from 'node:child_process' + +// Each UI's node invocation, verbatim what its standalone demo script ran +// (the stdio bin keeps --expose-internals for the cordis Loader's HMR path). +const UIS = new Map([ + ['repl', ['--expose-internals', '--import', 'tsx', 'packages/ui/stdio-agent/src/bin.ts', 'examples/code-agent/cordis.yml']], + ['acp', ['--import', 'tsx', 'packages/ui/acp-agent/src/bin.ts', 'examples/acp-agent/code-mode.cordis.yml']], +]) + +const ui = process.argv[2] ?? 'repl' +const args = UIS.get(ui) +if (!args || process.argv.length > 3) { + console.error('usage: pnpm run demo:code-mode [repl|acp]') + process.exit(2) +} + +const child = spawn(process.execPath, args, { stdio: 'inherit' }) +child.on('exit', (code, signal) => { process.exit(signal !== null ? 1 : code ?? 1) }) From 9fddbac09593484a0a66bff8b75ee881ee0ef1f1 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 13:02:19 +0800 Subject: [PATCH 076/119] refactor: unify the Code Mode demos on base-plus-overlay MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both demo:code-mode UIs now share one mechanism: the base example plus a same-shaped code-mode.cordis.yml include overlay (insert the worker runtime, flip tools.mode). Previously the REPL side was a hand-forked example (examples/code-agent) that had also silently diverged — it dropped compaction and the subagent stack — so the demo's UI argument switched agents, not just surfaces. The fork is retired: coding-agent gains the overlay, a Code Mode README section absorbing code-agent's, and both of its tests (the keyless boot guard, retargeted at the overlay; the with-key RFC proof, which hand-mounts its own harness and moves untouched). The RFC's composed-surface and e2e-tier lines, the examples index, the AGENTS.md smoke table, and the dsh-tools README link now describe the overlay shape. Verified live: overlay keyless smoke, with-key code-mode e2e from its new home, demo:code-mode banner + EOF exit, and the acp handshake. --- .../feature/2026-06-15-code-mode.md | 4 +- examples/AGENTS.md | 3 +- examples/README.md | 6 +- examples/code-agent/README.md | 17 ---- examples/code-agent/cordis.yml | 84 ------------------- examples/code-agent/package.json | 7 -- examples/coding-agent/README.md | 17 +++- examples/coding-agent/code-mode.cordis.yml | 33 ++++++++ .../tests/code-mode-keyless-smoke.e2e.ts} | 23 ++--- .../tests/code-mode.e2e.ts | 6 +- packages/core/tools/README.md | 2 +- scripts/demo-code-mode.mjs | 18 ++-- 12 files changed, 79 insertions(+), 141 deletions(-) delete mode 100644 examples/code-agent/README.md delete mode 100644 examples/code-agent/cordis.yml delete mode 100644 examples/code-agent/package.json create mode 100644 examples/coding-agent/code-mode.cordis.yml rename examples/{code-agent/tests/keyless-smoke.e2e.ts => coding-agent/tests/code-mode-keyless-smoke.e2e.ts} (75%) rename examples/{code-agent => coding-agent}/tests/code-mode.e2e.ts (96%) diff --git a/docs/rfc/implemented/feature/2026-06-15-code-mode.md b/docs/rfc/implemented/feature/2026-06-15-code-mode.md index 5ce9d784b9..4cc373c65c 100644 --- a/docs/rfc/implemented/feature/2026-06-15-code-mode.md +++ b/docs/rfc/implemented/feature/2026-06-15-code-mode.md @@ -90,7 +90,7 @@ What exists now: - **The seam**: `packages/code-runtime/` — `@deepseek-ai/dsh-code-runtime` (abstract `CodeRuntime`, the vocabulary above, `ctx.codeRuntime`) and `@deepseek-ai/dsh-code-runtime-worker` (the worker-thread backend, every cap a validated config field). Rows in the service map, capability-seams graph, config catalog, and cordis catalog. - **The registry surface**: `ToolRegistry`'s first config (`mode`), the mode-aware wire contribution, the `tools:sdk` section, `jsonSchemaToTs`/`renderToolsSdk` (exported), `run_code` + the dispatch bridge + `CodeRunFailedError`, and the `tool/code-dispatch` log event (declaration-merged into `SessionEventMap`, regenerated into the persistence catalog; `run_code` in the tool catalog). -- **The composed surface**: the `tools` config forwards through `agent-core` and both app packages (`stdio-agent`, `acp-agent`); `examples/code-agent` + `demo:code-mode` run the worker runtime under `mode: 'code'`; the adding-a-tool cookbook states that a registered tool is reachable from programs for free, and the tool-pipeline doc shows sub-dispatches re-entering both waterfalls. +- **The composed surface**: the `tools` config forwards through `agent-core` and both app packages (`stdio-agent`, `acp-agent`); `demo:code-mode` boots each UI example's `code-mode.cordis.yml` overlay (the worker runtime + `mode: 'code'` over the base tree); the adding-a-tool cookbook states that a registered tool is reachable from programs for free, and the tool-pipeline doc shows sub-dispatches re-entering both waterfalls. - **Interactions inherited by deployments**: a `toolOrder` naming native tools rejects every assembly under `'code'` (update or drop the order config when switching modes); sub-call `additionalContext` is dropped by the bridge (a plural context channel is deferred until a real hook needs it through Code Mode); sub-dispatch stays serialized until tools can declare concurrency safety — the same metadata the native parallel-dispatch TODO waits on. ## Testing @@ -99,7 +99,7 @@ What the suites pin, per tier: - **Unit — worker runtime** (real workers, no mocks): output/value capture and log-source attribution; error kinds (exception incl. non-erasable syntax, abort, worker-exit under OOM); the two budgets from both sides (a hot loop behind an un-awaited pending dispatch dies at `computeMs` busy time; a program idling on a slow binding outlives `computeMs` and dies only at `maxWallMs`); binding-bridge hostility (junk/forged port traffic incl. non-object messages and forged `log`/`done` cap bypass attempts, unknown names, duplicate ids, post-settlement replies, `__proto__`/`constructor`/`toString` binding names); structured-clone fallback and cap truncation; `env` emptiness verified from inside a program; dispose-awaits-exit. A real-load-path e2e runs the BUILT package under plain `node` so the worker entry resolves both unbuilt (tsx) and built — the published-artifact guard from [docs/testing.md](../../../testing.md). - **Unit — registry integration**: the codegen table (DSL subset, quoted names, `unknown` degradation, byte-identical determinism); provider contribution per mode (`'native'` unchanged, `'code'` exactly `[run_code]`, `'both'` all + `run_code`); `toolOrder × mode` rejection; missing-runtime / wrong-language loud failures; serialization non-overlap (a probe tool records enter/exit under `Promise.all`); abort aborting the in-flight sub-dispatch and abandoning queued ones; binding rejection on `isError` and on JSON-unrepresentable arguments; `CodeRunFailedError` → structured `isError` carrying kind + logs; `tool/code-dispatch` payloads (JSON-normalized arguments identical to what dispatched); `deriveMessages()` ignoring the event; sub-call `additionalContext` suppression; HMR safety (disposing the registry removes the tool and the section). -- **e2e (with-key, self-skips)**: a real model under `mode: 'code'` composes two bash calls in one program (`examples/code-agent/tests/code-mode.e2e.ts`) — every logged `request/header` carries exactly `[run_code]`, the dispatch events land under the parent call, the file the program wrote exists, and the final answer is the curated output. +- **e2e (with-key, self-skips)**: a real model under `mode: 'code'` composes two bash calls in one program (`examples/coding-agent/tests/code-mode.e2e.ts`) — every logged `request/header` carries exactly `[run_code]`, the dispatch events land under the parent call, the file the program wrote exists, and the final answer is the curated output. - **Snapshot (keyless replay)**: goldens for a `run_code` turn under `'code'` and `'both'` (`code-mode-turn`, `both-mode-turn`), each its own header-pinning class — the SDK section text, the collapsed header tool list, the dispatch events, and the result card are committed and replayed. ## Alternatives considered diff --git a/examples/AGENTS.md b/examples/AGENTS.md index 177ee18aa0..1434c46667 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -20,8 +20,7 @@ A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_P | Example | Keyless smoke | With-key smoke | |---|---|---| | `echo-agent` | `tests/echo.e2e.ts` — boots the real `cordis.yml`, drives the echo tool round-trip and the direct canned reply | **N/A — keyless by nature** (the `mock-echo` model has no real provider) | -| `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified | -| `code-agent` | `tests/keyless-smoke.e2e.ts` — the Code Mode boot guard | `tests/code-mode.e2e.ts` — a real model composes two bash calls in one `run_code` program; collapsed header, dispatch events, written file all verified | +| `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit; `tests/code-mode-keyless-smoke.e2e.ts` — the same boot guard for the Code Mode overlay | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified; `tests/code-mode.e2e.ts` — a real model composes two bash calls in one `run_code` program; collapsed header, dispatch events, written file all verified | | `acp-agent` | `pnpm run test:snapshot` — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); `tests/acp.e2e.ts` also asserts stdout purity without a key | `tests/acp.e2e.ts` — real ACP prompt, verifies a file the agent wrote; `tests/hooks.e2e.ts` — a real `PreToolUse` hook blocks bash, verifies the file is NOT written | See [the root AGENTS.md](../AGENTS.md) for repo-wide conventions and [docs/architecture.md](../docs/architecture.md) for the design. diff --git a/examples/README.md b/examples/README.md index 3027d01f0a..56c10f676b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,11 +19,7 @@ A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + th Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details. -## code-agent - -The coding agent flipped to **Code Mode**: the worker-thread code runtime is loaded and the tool registry runs `mode: code`, so the model gets exactly one wire tool — `run_code` — plus a generated TypeScript SDK section, and composes bash/read/write/edit/todo_write by writing a program whose output it curates. - -Run with: `pnpm run demo:code-mode` (needs `DEEPSEEK_API_KEY`; the REPL is the default UI — `acp` as the argument serves the acp-agent example's Code Mode overlay instead). See [code-agent/README.md](code-agent/README.md) for what to try and how it differs from coding-agent. +Its `code-mode.cordis.yml` overlay flips the same tree to **Code Mode**: the worker-thread code runtime is loaded and the tool registry runs `mode: code`, so the model gets exactly one wire tool — `run_code` — plus a generated TypeScript SDK section, and composes the other tools by writing a program whose output it curates. Run with: `pnpm run demo:code-mode` (the REPL is the default UI; `acp` as the argument serves the acp-agent example's same-shaped overlay instead) — see the [Code Mode section](coding-agent/README.md#code-mode) for what to try. ## acp-agent diff --git a/examples/code-agent/README.md b/examples/code-agent/README.md deleted file mode 100644 index 6e08a883a3..0000000000 --- a/examples/code-agent/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# code-agent — the Code Mode demo - -The [Code Mode](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) form of the coding agent: instead of one native tool call per step, the model is offered exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK section declaring every other registered tool (`bash`, `read`, `write`, `edit`, `todo_write`). The model composes tools by writing a program; the program runs in a fresh worker thread (`@deepseek-ai/dsh-code-runtime-worker`), its tool calls bridge back through the ordinary `tools/pre-execute`/`post-execute` pipeline one at a time, each is logged as a `tool/code-dispatch` session event, and ONLY what the program prints or returns re-enters the model's context. - -```sh -pnpm run demo:code-mode # needs DEEPSEEK_API_KEY (repo-root .env works) -``` - -Try a task that spans several tool calls, e.g.: - -> Count the lines of every `*.md` file under docs/ and write the three largest to summary.txt. - -and watch the transcript: one `run_code` call, a program looping over tools, and a result the model curated instead of five round-trips of raw tool output. - -Two lines of `cordis.yml` make the difference from [examples/coding-agent](../coding-agent/README.md): the `code-runtime` entry (the worker-thread backend registering `ctx.codeRuntime`) and `tools: { mode: code }` on the app (flip it to `both` to offer native calls AND `run_code` side by side; remove both lines and it IS the coding agent). - -Tests: `tests/keyless-smoke.e2e.ts` boots the real `cordis.yml` through the Loader with no prompt (the export-shape guard); `tests/code-mode.e2e.ts` is the with-key proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed, and the curated answer came back. diff --git a/examples/code-agent/cordis.yml b/examples/code-agent/cordis.yml deleted file mode 100644 index e4bb4de1e5..0000000000 --- a/examples/code-agent/cordis.yml +++ /dev/null @@ -1,84 +0,0 @@ -# The code-agent plugin tree: the Code Mode demo. The same spine as -# examples/coding-agent — the DeepSeek adapter, local bash, filesystem and -# todo tool stacks over the stdio chat app — with TWO differences that turn -# it into Cloudflare-style Code Mode: -# -# 1. `code-runtime` loads the worker-thread code-execution backend -# (`ctx.codeRuntime`): one fresh Node worker per run, TypeScript in. -# 2. `stdio-agent` sets `tools: { mode: code }`, so the model is offered -# exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK -# prompt section declaring bash/read/write/edit/todo_write; the model -# composes them by WRITING A PROGRAM, and only what it prints or -# returns re-enters its context. -# -# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the -# environment — the dsh-stdio-agent bin loads the gitignored repo-root .env -# first. cordis.yml reads them via the `!!js` tag. - -# Hot-module reload for the dev/demo loop (needs `node --expose-internals`). -- id: hmr - name: '@cordisjs/plugin-hmr' - config: - root: ['.'] - -# The DeepSeek adapter. -- id: llm-deepseek - name: '@deepseek-ai/dsh-llm-deepseek' - config: - apiKey: !!js process.env.DEEPSEEK_API_KEY - baseURL: !!js process.env.DEEPSEEK_BASE_URL - models: - - deepseek-v4-pro - - deepseek-v4-flash - -# Local bash executor for the spine's `bash` tool schemas. -- id: bash - name: '@deepseek-ai/dsh-bash-local' - config: - timeoutMs: 60000 - -# The code-execution backend: `run_code` programs execute here, in one fresh -# worker thread per run with an empty environment, port-bridged tool -# bindings, and busy-time/wall-clock/heap caps (all overridable here). -- id: code-runtime - name: '@deepseek-ai/dsh-code-runtime-worker' - -# The stdio chat app with the registry flipped to Code Mode: the wire tool -# list collapses to [run_code] and the `tools:sdk` prompt section carries the -# generated TypeScript declarations for every other registered tool. -- id: stdio-agent - name: '@deepseek-ai/dsh-stdio-agent' - config: - model: deepseek-v4-flash - tools: - mode: code - # Set RESUME_SESSION_ID to continue a prior persisted session (the ids - # live under ./.sessions); unset starts a fresh session each run. - resumeSessionId: !!js process.env.RESUME_SESSION_ID - persistenceRoot: './.sessions' - welcome: 'code-mode agent ready. Give it a multi-tool task.' - persona: | - You are code-agent, a coding assistant powered by the {{model}} model. - - You work by writing TypeScript programs for run_code: batch related - tool work into one program, loop and branch where it helps, and print - or return ONLY the findings that matter. - -# The model-facing todo_write tool: whole-list task tracking written to the -# session log (todo/write), rendered as a stdio checklist. -- id: tool-todo - name: '@deepseek-ai/dsh-tool-todo' - -# Filesystem capability stack: local provider, read-before-write/edit policy -# gate, then the model-facing read/write/edit tools — all reachable from a -# run_code program as `tools.read(...)` / `tools.write(...)` / `tools.edit(...)`. -- id: fs-local - name: '@deepseek-ai/dsh-fs-local' - config: - cwd: !!js process.cwd() - -- id: fs-policy - name: '@deepseek-ai/dsh-fs-policy' - -- id: tool-fs - name: '@deepseek-ai/dsh-tool-fs' diff --git a/examples/code-agent/package.json b/examples/code-agent/package.json deleted file mode 100644 index 0aa0e52c52..0000000000 --- a/examples/code-agent/package.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "code-agent-example", - "private": true, - "version": "0.0.1", - "type": "module", - "description": "Runnable demo: Code Mode — the model writes TypeScript against the tool registry" -} diff --git a/examples/coding-agent/README.md b/examples/coding-agent/README.md index 4b15d2dc5a..7731aa8f09 100644 --- a/examples/coding-agent/README.md +++ b/examples/coding-agent/README.md @@ -31,6 +31,21 @@ RESUME_SESSION_ID= pnpm run demo:repl The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent. +## Code Mode + +[`code-mode.cordis.yml`](code-mode.cordis.yml) is this same tree flipped to [Code Mode](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md): an include overlay over `./cordis.yml` whose two patches insert the worker-thread code runtime (`@deepseek-ai/dsh-code-runtime-worker`, registering `ctx.codeRuntime`) and set `tools: { mode: code }` on the app. The model is then offered exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK section declaring every other registered tool; it composes them by writing a program, each program tool call bridges back through the ordinary `tools/pre-execute`/`post-execute` pipeline one at a time and is logged as a `tool/code-dispatch` session event, and ONLY what the program prints or returns re-enters its context. (Flip the mode to `both` to offer native calls AND `run_code` side by side.) + +```sh +pnpm run demo:code-mode # this overlay under the REPL (default UI) +pnpm run demo:code-mode acp # the acp-agent example's same-shaped overlay +``` + +Try a task that spans several tool calls, e.g.: + +> Count the lines of every `*.md` file under docs/ and write the three largest to summary.txt. + +and watch the transcript: one `run_code` call, a program looping over tools, and a result the model curated instead of five round-trips of raw tool output. + ## What each leaf entry demonstrates This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads one app package, and adds product tools that are intentionally outside the shared spine. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (console logger, JSONL persistence, readline UI, the pre-created `main` agent) live inside the [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent) app and the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle it loads; the leaf wires the backends and model-facing optional tools: @@ -54,4 +69,4 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads - `tests/compaction.e2e.ts` — the compaction smoke: a real multi-step bash task runs with a deliberately tiny context window so the auto-compaction listener fires MID-SESSION. Verifies the WORLD — a `compact/start…end` pair landed in the real log, the surface shrank (a replace node shadowed older nodes), and the agent still produced a correct final answer after compaction. - `tests/todo-write.e2e.ts` — a real model drives the real `todo_write` tool and the test verifies the resulting `todo/write` session event. -These self-skip without `DEEPSEEK_API_KEY`. The keyless boot smoke is `tests/keyless-smoke.e2e.ts` (boots the full real tree with a dummy key and no prompt, so no model call), which runs in the default e2e gate. +These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. The keyless boot smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts` (the full real tree, dummy key, no prompt → no model call) and `tests/code-mode-keyless-smoke.e2e.ts` (the same guard for the Code Mode overlay). diff --git a/examples/coding-agent/code-mode.cordis.yml b/examples/coding-agent/code-mode.cordis.yml new file mode 100644 index 0000000000..ac4ce03570 --- /dev/null +++ b/examples/coding-agent/code-mode.cordis.yml @@ -0,0 +1,33 @@ +# Code Mode overlay: the live coding-agent tree (./cordis.yml) with two +# load-time patches — the app entry's config gains `tools: { mode: code }` +# (the registry offers exactly one wire tool, run_code, plus the generated +# TypeScript SDK prompt section declaring bash/read/write/edit/subagent/ +# todo_write) and the worker-thread code runtime joins the tree as +# `ctx.codeRuntime`. The dsh-stdio-agent bin boots this file for +# `pnpm run demo:code-mode` (the acp-agent example carries the same-shaped +# overlay for the `acp` UI). A config patch REPLACES the entry's whole +# config, so the base entry's fields are restated verbatim; only `tools`, +# the welcome, and the persona's second paragraph are Code Mode deltas. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ./cordis.yml + patches: + - id: stdio-agent + name: '@deepseek-ai/dsh-stdio-agent' + config: + model: deepseek-v4-flash + resumeSessionId: !!js process.env.RESUME_SESSION_ID + persistenceRoot: './.sessions' + tools: + mode: code + welcome: 'code-mode agent ready. Give it a multi-tool task.' + persona: | + You are coding-agent, a coding assistant powered by the {{model}} model. + + You work by writing TypeScript programs for run_code: batch related + tool work into one program, loop and branch where it helps, and print + or return ONLY the findings that matter. + - insert: + - id: code-runtime + name: '@deepseek-ai/dsh-code-runtime-worker' diff --git a/examples/code-agent/tests/keyless-smoke.e2e.ts b/examples/coding-agent/tests/code-mode-keyless-smoke.e2e.ts similarity index 75% rename from examples/code-agent/tests/keyless-smoke.e2e.ts rename to examples/coding-agent/tests/code-mode-keyless-smoke.e2e.ts index d5913e48d5..7894e9ff9f 100644 --- a/examples/code-agent/tests/keyless-smoke.e2e.ts +++ b/examples/coding-agent/tests/code-mode-keyless-smoke.e2e.ts @@ -6,11 +6,12 @@ import { fileURLToPath } from 'node:url' import { afterEach, describe, expect, it } from 'vitest' /** - * Keyless Loader-path smoke for examples/code-agent: boot the REAL example - * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` - * (the cordis Loader, `unwrapExports`, the full plugin tree incl. the - * worker-thread code runtime and the registry in `mode: code`), then close - * stdin with no prompt and assert the ready banner + a clean exit. + * Keyless Loader-path smoke for the Code Mode overlay: boot the REAL + * example through the `@deepseek-ai/dsh-stdio-agent` bin against + * `code-mode.cordis.yml` (the cordis Loader, `unwrapExports`, the include + * patches over ./cordis.yml, the worker-thread code runtime, and the + * registry in `mode: code`), then close stdin with no prompt and assert + * the Code Mode banner + a clean exit. * * No prompt is ever sent, so the model is NEVER called and no `run_code` * turn happens — a dummy key lets `llm-deepseek`'s key-PRESENT check boot @@ -19,7 +20,7 @@ import { afterEach, describe, expect, it } from 'vitest' */ const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url)) -const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) +const configPath = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url)) const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) // Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig // `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside @@ -37,12 +38,12 @@ afterEach(async () => { }) async function bootAndEof(): Promise<{ stdout: string; code: number }> { - workdir = await mkdtemp(join(tmpdir(), 'code-agent-smoke-')) + workdir = await mkdtemp(join(tmpdir(), 'code-mode-smoke-')) const cwd = workdir return new Promise((resolve, reject) => { const proc = spawn( process.execPath, - // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:code-mode). + // --expose-internals: the included cordis.yml loads the HMR plugin (mirrors demo:code-mode). ['--expose-internals', '--import', tsxLoader, binScript, configPath], { cwd, @@ -66,13 +67,13 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> { const timer = setTimeout(() => { proc.kill('SIGKILL') - reject(new Error(`code-agent did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`)) + reject(new Error(`code-mode overlay did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`)) }, 10_000) proc.on('exit', (code) => { clearTimeout(timer) if (code === 0) resolve({ stdout, code }) - else reject(new Error(`code-agent exited ${code}. stderr:\n${stderr}`)) + else reject(new Error(`code-mode overlay exited ${code}. stderr:\n${stderr}`)) }) proc.on('error', (err) => { clearTimeout(timer); reject(err) }) @@ -81,7 +82,7 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> { }) } -describe('code-agent keyless smoke (real cordis.yml via the Loader)', () => { +describe('code-mode overlay keyless smoke (real code-mode.cordis.yml via the Loader)', () => { it('boots the Code Mode plugin tree, prints its banner, and exits cleanly on EOF', async () => { const { stdout, code } = await bootAndEof() expect(code).toBe(0) diff --git a/examples/code-agent/tests/code-mode.e2e.ts b/examples/coding-agent/tests/code-mode.e2e.ts similarity index 96% rename from examples/code-agent/tests/code-mode.e2e.ts rename to examples/coding-agent/tests/code-mode.e2e.ts index 6b0771380d..512688d88d 100644 --- a/examples/code-agent/tests/code-mode.e2e.ts +++ b/examples/coding-agent/tests/code-mode.e2e.ts @@ -22,11 +22,11 @@ import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker' * `[run_code]` as the wire tool list, each sub-call landed as a * `tool/code-dispatch` event, the file the program wrote exists on disk, and * the final answer is the program's curated output. Key-gated (see - * vitest.e2e.config.ts); the keyless Loader-path smoke lives in - * `keyless-smoke.e2e.ts`. + * vitest.e2e.config.ts); the keyless Loader-path smoke of the overlay lives + * in `code-mode-keyless-smoke.e2e.ts`. */ -const PERSONA = 'You are code-agent. You work by writing TypeScript programs for run_code: ' +const PERSONA = 'You are coding-agent. You work by writing TypeScript programs for run_code: ' + 'batch related tool work into one program and print or return ONLY the findings that matter.' let ctx: Context | undefined diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index c0c7cfe437..2ca93b94af 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -133,7 +133,7 @@ Under `mode: code` (or `both`) the registry turns the tool surface into a progra - **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 the logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes the underlying `ctx.tools.execute()` calls one at a time in submission order — the tool contract carries no concurrency-safety metadata yet), gated by `tools/pre-execute`/`tools/post-execute` like any native call (a deny reaches the program as a binding rejection), and logged as one `tool/code-dispatch` session event (log-only: `deriveMessages()` never surfaces it) with the deterministic sub-id `:code:`. A failed sub-call REJECTS the program-side promise with the tool's error text — real code error handling, no bespoke envelope. A sub-call's `additionalContext` is deliberately DROPPED (no safe outlet mid-run without breaking tool-call/result adjacency; deferred until a real hook needs it through Code Mode). - **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. -The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free — under `code`, the assembled tool list is exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code-mode` ([examples/code-agent](../../../examples/code-agent/README.md)); `pnpm run demo:code-mode acp` serves the same mode over ACP instead of the REPL. +The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free — under `code`, the assembled tool list is exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code-mode` ([the coding-agent example's Code Mode overlay](../../../examples/coding-agent/README.md#code-mode)); `pnpm run demo:code-mode acp` serves the same mode over ACP instead of the REPL. ### What is NOT here (TODO) diff --git a/scripts/demo-code-mode.mjs b/scripts/demo-code-mode.mjs index 465e5f2982..a93ea98173 100644 --- a/scripts/demo-code-mode.mjs +++ b/scripts/demo-code-mode.mjs @@ -1,18 +1,20 @@ /** * Boot the Code Mode demo under the UI named on the command line: * `pnpm run demo:code-mode [repl|acp]`, default `repl`. Code Mode is the - * point — the UI is just the surface it happens to wear: `repl` starts the - * stdio REPL over examples/code-agent, `acp` starts the ACP server over - * examples/acp-agent's code-mode overlay. Both need DEEPSEEK_API_KEY - * (repo-root .env works). Anything else on the command line is a - * misconfiguration and fails loud with usage. + * point — the UI is just the surface it happens to wear: each UI boots its + * base example through that example's `code-mode.cordis.yml` overlay + * (include ./cordis.yml, flip `tools.mode` to `code`, insert the + * worker-thread code runtime). Both need DEEPSEEK_API_KEY (repo-root .env + * works). Anything else on the command line is a misconfiguration and + * fails loud with usage. */ import { spawn } from 'node:child_process' -// Each UI's node invocation, verbatim what its standalone demo script ran -// (the stdio bin keeps --expose-internals for the cordis Loader's HMR path). +// Each UI's node invocation, verbatim what its base demo script runs plus +// the overlay config (the stdio bin keeps --expose-internals for the cordis +// Loader's HMR path). const UIS = new Map([ - ['repl', ['--expose-internals', '--import', 'tsx', 'packages/ui/stdio-agent/src/bin.ts', 'examples/code-agent/cordis.yml']], + ['repl', ['--expose-internals', '--import', 'tsx', 'packages/ui/stdio-agent/src/bin.ts', 'examples/coding-agent/code-mode.cordis.yml']], ['acp', ['--import', 'tsx', 'packages/ui/acp-agent/src/bin.ts', 'examples/acp-agent/code-mode.cordis.yml']], ]) From fc6db791f18a008db44345101e47d095e8e4270b Mon Sep 17 00:00:00 2001 From: Ziya <199893125+ZiyaZhang@users.noreply.github.com> Date: Wed, 8 Jul 2026 20:45:05 -0700 Subject: [PATCH 077/119] refactor(compact): extract the shared transcript renderer into dsh-compact Move compact-basic's private _extractText/_blocksToText into the interface package as renderTranscript/renderContentBlocks, so the summarize path and a future recall read path render one span identically. Byte-identical output vs the private helpers it replaces; compact-basic delegates. --- docs/cordis-catalog/services.md | 2 +- packages/compact/compact-basic/src/index.ts | 99 +------------ .../compact-basic/tests/compact-basic.spec.ts | 2 +- packages/compact/compact/README.md | 2 +- packages/compact/compact/src/index.ts | 1 + packages/compact/compact/src/render.ts | 118 +++++++++++++++ packages/compact/compact/tests/render.spec.ts | 138 ++++++++++++++++++ 7 files changed, 262 insertions(+), 100 deletions(-) create mode 100644 packages/compact/compact/src/render.ts create mode 100644 packages/compact/compact/tests/render.spec.ts diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 26126c4481..53251518b4 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -102,7 +102,7 @@ abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise ``` -Source: [`packages/compact/compact/src/index.ts:63`](../../packages/compact/compact/src/index.ts) +Source: [`packages/compact/compact/src/index.ts:64`](../../packages/compact/compact/src/index.ts) ## `ctx.fs` — `FileSystem` (abstract seam) diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts index 03f7c9ab4b..3916441402 100644 --- a/packages/compact/compact-basic/src/index.ts +++ b/packages/compact/compact-basic/src/index.ts @@ -30,7 +30,7 @@ */ import { Context } from 'cordis' -import { CompactService } from '@deepseek-ai/dsh-compact' +import { CompactService, renderTranscript } from '@deepseek-ai/dsh-compact' import type { CompactionResult } from '@deepseek-ai/dsh-compact' import { BlockAssembler } from '@deepseek-ai/dsh-llm' import type { ContentBlock, FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm' @@ -483,7 +483,7 @@ export class BasicCompactService extends CompactService { try { // --- Extract text and summarize --- - const text = this._extractText(session, shadowedSeqs) + const text = renderTranscript(session.events, shadowedSeqs) const { summary, model, maxTokens } = await this.summarize(text, agent, signal) // Estimate token count of the shadowed content for provenance. @@ -679,101 +679,6 @@ export class BasicCompactService extends CompactService { } return null } - - /** - * Extract plain-text conversation from a set of surface node seqs, for - * feeding into the summarization model. Walks the seqs in the order given - * (surface order, as `compactRegion` slices the surface-node list) so the - * summary follows the conversation as the model sees it — which, after a - * `replace`, is NOT ascending log-seq order (a high-seq summary node heads the - * surface before older retained lower-seq nodes). - */ - private _extractText(session: Session, seqs: number[]): string { - const lines: string[] = [] - - // Walk seqs in the order given (surface order, as compactRegion slices the - // surface-node list) — NOT ascending log-seq order. After a replace the - // summary node carries a fresh high seq while sitting at the head of the - // surface before older retained lower-seq nodes, so a log-order scan would - // feed the transcript out of order and break the checkpoint-merge prompt. - for (const seq of seqs) { - const event = session.events[seq] - /* v8 ignore next -- seq is a surface-node seq, always a valid log index by construction */ - if (!event) continue - - switch (event.type) { - case 'user/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`User: ${text}`) - break - } - case 'assistant/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`Assistant: ${text}`) - break - } - case 'tool/result': { - const text = this._blocksToText(event.data.content) - const label = event.data.isError ? 'Tool error' : 'Tool result' - if (text) lines.push(`${label} (call ${event.data.callId}): ${text}`) - break - } - case 'context/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`[Context: ${text}]`) - break - } - case 'steering/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`[Steering: ${text}]`) - break - } - // SessionEventMap is merge-extensible — unknown types are - // non-message events that carry no extractable text. - /* v8 ignore next 2 -- seqs only name surface nodes, always one of the 5 handled SurfaceEventTypes; unreachable */ - default: - break - } - } - - return lines.join('\n\n') - } - - /** - * Render content blocks to a single plain-text string for the summarization - * prompt. Text and reasoning contribute their text; every other block type - * contributes a type-tagged placeholder (`[tool-call: name(args)]`, - * `[tool-result: …]`, …) so the summarizer is told what non-text content - * existed in the region rather than silently losing it. Blocks join with - * newlines; empty-text blocks contribute nothing. - */ - private _blocksToText(blocks: readonly ContentBlock[]): string { - const parts: string[] = [] - for (const block of blocks) { - switch (block.type) { - case 'text': - if (block.text) parts.push(block.text) - break - case 'reasoning': - if (block.text) parts.push(`[reasoning: ${block.text}]`) - break - case 'tool-call': - parts.push(`[tool-call: ${block.name}(${block.arguments})]`) - break - case 'tool-result': { - const inner = this._blocksToText(block.content) - parts.push(inner ? `[tool-result: ${inner}]` : '[tool-result]') - break - } - // ContentBlockMap is merge-extensible — render an unknown block as a - // bare type-tagged placeholder so a plugin-added block type is still - // signalled to the summarizer rather than dropped. - default: - parts.push(`[${(block as ContentBlock).type}]`) - } - } - return parts.join('\n') - } } export default BasicCompactService diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index 990d60190a..9cd61a95be 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -1278,7 +1278,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => }) }) -describe('BasicCompactService._extractText branches', () => { +describe('BasicCompactService transcript rendering (delegated to dsh-compact)', () => { it('renders reasoning, context, and steering messages', async () => { const svc = createTestService() const s = new Session(SessionId('rich')) diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md index 54bdcc7f4e..e908412d16 100644 --- a/packages/compact/compact/README.md +++ b/packages/compact/compact/README.md @@ -6,7 +6,7 @@ This package is the interface tier of the compaction capability, split so each c | Package | Role | |---|---| -| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` | +| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + the shared transcript renderer (`renderTranscript`/`renderContentBlocks`) | | `@deepseek-ai/dsh-compact-basic` (deferred) | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization | | `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` | diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts index cc190ccd87..931e8274cf 100644 --- a/packages/compact/compact/src/index.ts +++ b/packages/compact/compact/src/index.ts @@ -26,6 +26,7 @@ import type { Session } from '@deepseek-ai/dsh-session' import type { CompactionResult } from './types.ts' export type { CompactionResult } from './types.ts' +export { renderContentBlocks, renderTranscript } from './render.ts' /** Minimal agent context compaction needs without depending on the agent package. */ export interface CompactAgentContext { diff --git a/packages/compact/compact/src/render.ts b/packages/compact/compact/src/render.ts new file mode 100644 index 0000000000..6e977df007 --- /dev/null +++ b/packages/compact/compact/src/render.ts @@ -0,0 +1,118 @@ +/** + * Plain-text transcript rendering over session events: the shared projection + * used wherever a compaction-class consumer needs "what a model once saw" as + * readable text — a summarizer's input, or a recall tool's output. + * + * Extracted from the basic backend's private helpers so the summarize path and + * the recall read path render one span identically (two renderers would drift, + * and a recall reader would then see a different transcript than the one the + * summary was written from). Both functions are pure over their arguments: no + * session access beyond the provided events, no clock, no randomness — a + * rendered span is a pure function of the log, so replay reproduces it + * byte-identically. + * + * @module @deepseek-ai/dsh-compact/render + */ + +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { SessionEvent } from '@deepseek-ai/dsh-session' + +/** + * Render content blocks to a single plain-text string. Text and reasoning + * contribute their text (reasoning wrapped as `[reasoning: …]`); every other + * block type contributes a type-tagged placeholder (`[tool-call: name(args)]`, + * `[tool-result: …]`, …) so the reader is told what non-text content existed + * rather than silently losing it. A `tool-result` block recurses into its + * nested content (`[tool-result: ]`), falling back to a bare + * `[tool-result]` when the nested content renders to nothing. Blocks join + * with newlines; empty-text blocks contribute nothing. + * + * @param blocks - the content blocks to render. + * @returns the newline-joined plain-text rendering; empty string when nothing renders. + */ +export function renderContentBlocks(blocks: readonly ContentBlock[]): string { + const parts: string[] = [] + for (const block of blocks) { + switch (block.type) { + case 'text': + if (block.text) parts.push(block.text) + break + case 'reasoning': + if (block.text) parts.push(`[reasoning: ${block.text}]`) + break + case 'tool-call': + parts.push(`[tool-call: ${block.name}(${block.arguments})]`) + break + case 'tool-result': { + const inner = renderContentBlocks(block.content) + parts.push(inner ? `[tool-result: ${inner}]` : '[tool-result]') + break + } + // ContentBlockMap is merge-extensible — render an unknown block as a + // bare type-tagged placeholder so a plugin-added block type is still + // signalled to the reader rather than dropped. + default: + parts.push(`[${(block as ContentBlock).type}]`) + } + } + return parts.join('\n') +} + +/** + * Render a set of surface-node seqs as a `User:`/`Assistant:`/`Tool result:` + * transcript. Walks `seqs` in the order given — callers pass surface order + * (e.g. a `compactRegion` slice of the surface-node list), which after a + * `replace` is NOT ascending log-seq order (a high-seq summary node can sit at + * the head of the surface before older retained lower-seq nodes); a log-order + * scan would render the transcript out of order. + * + * Only the five surface (message-producing) event types render; a seq naming + * any other event type contributes nothing. `SessionEventMap` is + * merge-extensible, so unknown types are simply non-message events with no + * renderable text. + * + * @param events - the session log the seqs index into (`session.events`). + * @param seqs - the surface-node seqs to render, in surface order. + * @returns the transcript, entries joined by blank lines; empty string when nothing renders. + */ +export function renderTranscript(events: readonly SessionEvent[], seqs: readonly number[]): string { + const lines: string[] = [] + + for (const seq of seqs) { + const event = events[seq] + if (!event) continue + + switch (event.type) { + case 'user/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`User: ${text}`) + break + } + case 'assistant/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`Assistant: ${text}`) + break + } + case 'tool/result': { + const text = renderContentBlocks(event.data.content) + const label = event.data.isError ? 'Tool error' : 'Tool result' + if (text) lines.push(`${label} (call ${event.data.callId}): ${text}`) + break + } + case 'context/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`[Context: ${text}]`) + break + } + case 'steering/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`[Steering: ${text}]`) + break + } + default: + break + } + } + + return lines.join('\n\n') +} diff --git a/packages/compact/compact/tests/render.spec.ts b/packages/compact/compact/tests/render.spec.ts new file mode 100644 index 0000000000..1a22296565 --- /dev/null +++ b/packages/compact/compact/tests/render.spec.ts @@ -0,0 +1,138 @@ +import { describe, expect, it } from 'vitest' +import { renderContentBlocks, renderTranscript } from '@deepseek-ai/dsh-compact' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import { CallId } from '@deepseek-ai/dsh-llm' + +function session(): Session { + return new Session(SessionId('render-spec')) +} + +describe('renderContentBlocks', () => { + it('renders text blocks verbatim and skips empty ones', () => { + expect(renderContentBlocks([ + { type: 'text', text: 'hello' }, + { type: 'text', text: '' }, + { type: 'text', text: 'world' }, + ])).toBe('hello\nworld') + }) + + it('wraps reasoning, skipping empty reasoning', () => { + expect(renderContentBlocks([ + { type: 'reasoning', text: 'think' }, + { type: 'reasoning', text: '' }, + ])).toBe('[reasoning: think]') + }) + + it('renders tool-call as a name(args) placeholder', () => { + expect(renderContentBlocks([ + { type: 'tool-call', id: CallId('c1'), name: 'read', arguments: '{"filePath":"a"}' }, + ])).toBe('[tool-call: read({"filePath":"a"})]') + }) + + it('renders tool-result with nested content, and bare when empty', () => { + expect(renderContentBlocks([ + { type: 'tool-result', toolCallId: CallId('c1'), content: [{ type: 'text', text: 'ok' }] }, + { type: 'tool-result', toolCallId: CallId('c2'), content: [] }, + ])).toBe('[tool-result: ok]\n[tool-result]') + }) + + it('renders an unknown (merge-extended) block type as a bare type tag', () => { + const unknown = { type: 'image', data: 'zzz' } as unknown as ContentBlock + expect(renderContentBlocks([unknown])).toBe('[image]') + }) + + it('returns the empty string for no blocks', () => { + expect(renderContentBlocks([])).toBe('') + }) +}) + +describe('renderTranscript', () => { + it('renders each surface event type with its label, in the seq order given', () => { + const s = session() + const user = s.append('user/message', { + content: [{ type: 'text', text: 'fix the bug' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const assistant = s.append('assistant/message', { + turn: 0, step: 0, + content: [{ type: 'text', text: 'looking' }], + }, { surfaceOp: 'append' }) + const result = s.append('tool/result', { + turn: 0, step: 0, callId: CallId('c1'), + content: [{ type: 'text', text: 'exit 0' }], + isError: false, + }, { surfaceOp: 'append' }) + const context = s.append('context/message', { + content: [{ type: 'text', text: 'file changed' }], + source: { kind: 'plugin', plugin: 'fs' }, + }, { surfaceOp: 'append' }) + const steering = s.append('steering/message', { + turn: 0, + content: [{ type: 'text', text: 'stop that' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + + expect(renderTranscript(s.events, [user.seq, assistant.seq, result.seq, context.seq, steering.seq])).toBe([ + 'User: fix the bug', + 'Assistant: looking', + 'Tool result (call c1): exit 0', + '[Context: file changed]', + '[Steering: stop that]', + ].join('\n\n')) + }) + + it('labels an error tool result "Tool error"', () => { + const s = session() + const result = s.append('tool/result', { + turn: 0, step: 0, callId: CallId('c9'), + content: [{ type: 'text', text: 'boom' }], + isError: true, + }, { surfaceOp: 'append' }) + expect(renderTranscript(s.events, [result.seq])).toBe('Tool error (call c9): boom') + }) + + it('renders NON-log-order seqs in the order given (surface order after a replace)', () => { + const s = session() + const first = s.append('user/message', { + content: [{ type: 'text', text: 'first' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const second = s.append('user/message', { + content: [{ type: 'text', text: 'second' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + expect(renderTranscript(s.events, [second.seq, first.seq])).toBe('User: second\n\nUser: first') + }) + + it('skips events that render to nothing, non-message events, and seqs with no event', () => { + const s = session() + const empty = s.append('user/message', { + content: [{ type: 'text', text: '' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const emptyAssistant = s.append('assistant/message', { + turn: 0, step: 0, + content: [{ type: 'text', text: '' }], + }, { surfaceOp: 'append' }) + const emptyResult = s.append('tool/result', { + turn: 0, step: 0, callId: CallId('c3'), + content: [{ type: 'text', text: '' }], + isError: false, + }, { surfaceOp: 'append' }) + const emptyContext = s.append('context/message', { + content: [{ type: 'text', text: '' }], + source: { kind: 'plugin', plugin: 'fs' }, + }, { surfaceOp: 'append' }) + const emptySteering = s.append('steering/message', { + turn: 0, + content: [{ type: 'text', text: '' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + // A log-only (non-surface) event type: contributes nothing to a transcript. + const lock = s.append('compact/start', { turn: 0 }) + expect(renderTranscript(s.events, [ + empty.seq, emptyAssistant.seq, emptyResult.seq, emptyContext.seq, emptySteering.seq, lock.seq, 9999, + ])).toBe('') + }) +}) From c321819053c29468f79adb87dc66c7ff22f37668 Mon Sep 17 00:00:00 2001 From: pku-xht Date: Thu, 9 Jul 2026 13:42:03 +0800 Subject: [PATCH 078/119] rename: @deepseek-ai/dsh-subagent-process -> @deepseek-ai/dsh-subagent-subprocess MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The extracted library's name sat one edit away from @deepseek-ai/dsh-subagent-inprocess (process/inprocess), inviting a typo'd import to silently resolve to the wrong package. subagent-subprocess also reads as the deliberate counterpart to subagent-inprocess (in-process vs. subprocess), matching how the two shared drivers actually differ. Package directory, npm name, module doc, JSDoc module tags, test-file name and its temp-dir prefixes, the subagent-acp import and its Config/tsconfig/package.json references, root tsconfig.json/tsconfig.build.json/knip.json entries, and the packages/subagent group README all renamed together; regenerated docs/module-graph.md and docs/config-catalog.md. Pure rename — no behavior, export, or Config shape changed. --- docs/config-catalog.md | 2 +- docs/module-graph.md | 8 ++++---- knip.json | 2 +- packages/subagent/README.md | 4 ++-- packages/subagent/subagent-acp/README.md | 2 +- packages/subagent/subagent-acp/package.json | 4 ++-- packages/subagent/subagent-acp/src/run.ts | 2 +- .../subagent-acp/tests/subagent-acp.spec.ts | 2 +- packages/subagent/subagent-acp/tsconfig.json | 2 +- .../README.md | 4 ++-- .../package.json | 2 +- .../src/index.ts | 2 +- .../tests/subagent-subprocess.spec.ts} | 16 ++++++++-------- .../tsconfig.json | 0 pnpm-lock.yaml | 16 ++++++++-------- tsconfig.build.json | 2 +- tsconfig.json | 2 +- 17 files changed, 36 insertions(+), 36 deletions(-) rename packages/subagent/{subagent-process => subagent-subprocess}/README.md (86%) rename packages/subagent/{subagent-process => subagent-subprocess}/package.json (93%) rename packages/subagent/{subagent-process => subagent-subprocess}/src/index.ts (99%) rename packages/subagent/{subagent-process/tests/subagent-process.spec.ts => subagent-subprocess/tests/subagent-subprocess.spec.ts} (94%) rename packages/subagent/{subagent-process => subagent-subprocess}/tsconfig.json (100%) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 34cb543303..642a4d719a 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -884,4 +884,4 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them. - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts)) - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)) - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts)) -- `@deepseek-ai/dsh-subagent-process` ([`packages/subagent/subagent-process/src/index.ts`](../packages/subagent/subagent-process/src/index.ts)) +- `@deepseek-ai/dsh-subagent-subprocess` ([`packages/subagent/subagent-subprocess/src/index.ts`](../packages/subagent/subagent-subprocess/src/index.ts)) diff --git a/docs/module-graph.md b/docs/module-graph.md index 57fb397e54..c0e64c1d36 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -43,8 +43,8 @@ flowchart TD pkg_subagent_acp["subagent-acp"] pkg_subagent_fork["subagent-fork"] pkg_subagent_inprocess["subagent-inprocess"] - pkg_subagent_process["subagent-process"] pkg_subagent_spawn["subagent-spawn"] + pkg_subagent_subprocess["subagent-subprocess"] pkg_tool_subagent["tool-subagent"] end subgraph group_web["packages/web"] @@ -179,7 +179,7 @@ flowchart TD pkg_subagent_acp --> pkg_agent pkg_subagent_acp --> pkg_llm pkg_subagent_acp --> pkg_subagent - pkg_subagent_acp --> pkg_subagent_process + pkg_subagent_acp --> pkg_subagent_subprocess pkg_subagent_inprocess --> pkg_agent pkg_subagent_inprocess --> pkg_llm pkg_subagent_inprocess --> pkg_session @@ -220,7 +220,7 @@ flowchart TD | Package | Group | Depends on | | --- | --- | --- | | [`brand`](../packages/util/brand) | `util` | — | -| [`subagent-process`](../packages/subagent/subagent-process) | `subagent` | — | +| [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | — | | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — | | [`app-boot`](../packages/ui/app-boot) | `ui` | — | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — | @@ -260,7 +260,7 @@ flowchart TD | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) | -| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-process`](../packages/subagent/subagent-process) | +| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | diff --git a/knip.json b/knip.json index d4c44e9aa5..ecfd431c1c 100644 --- a/knip.json +++ b/knip.json @@ -70,7 +70,7 @@ "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/mock-acp-server.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, - "packages/subagent/subagent-process": { + "packages/subagent/subagent-subprocess": { "entry": ["tests/**/*.spec.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"], "ignoreDependencies": ["cordis"] diff --git a/packages/subagent/README.md b/packages/subagent/README.md index 38c64d22a5..87930167e9 100644 --- a/packages/subagent/README.md +++ b/packages/subagent/README.md @@ -8,10 +8,10 @@ The subagent seam: an agent delegating work to a child agent. Like the [bash](.. | `subagent-inprocess/` | Shared in-process run driver (pure lib; registers nothing) | — | | `subagent-spawn/` | In-process backend: a fresh child agent | (registers on `ctx.subagents`) | | `subagent-fork/` | In-process backend: a child seeded with the parent's completed-turn prefix | (registers on `ctx.subagents`) | -| `subagent-process/` | Shared out-of-process machinery: env scrub, dispose ladder, isolated config dirs (pure lib; registers nothing) | — | +| `subagent-subprocess/` | Shared out-of-process machinery: env scrub, dispose ladder, isolated config dirs (pure lib; registers nothing) | — | | `subagent-acp/` | Out-of-process backend: a child agent in a spawned subprocess, driven over ACP | (registers on `ctx.subagents`) | | `tool-subagent/` | Model-facing `subagent` delegation tool over `ctx.subagents` | (registers on `ctx.tools`) | -The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a pure library — both depend on it, neither on the other), the out-of-process `subagent-acp` backend builds on the `subagent-process` library (the credential env scrub, the dispose ladder, isolated config dirs) and ships alongside them here; the test-only `dsh-subagent-mock` (in [support](../support/README.md)) is separate. All **product** packages except the mock. +The interface lives at `subagent/subagent/`. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a pure library — both depend on it, neither on the other), the out-of-process `subagent-acp` backend builds on the `subagent-subprocess` library (the credential env scrub, the dispose ladder, isolated config dirs) and ships alongside them here; the test-only `dsh-subagent-mock` (in [support](../support/README.md)) is separate. All **product** packages except the mock. The proposal and design rationale: [docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md](../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md). diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md index 2cc330aefd..7fb087dcdc 100644 --- a/packages/subagent/subagent-acp/README.md +++ b/packages/subagent/subagent-acp/README.md @@ -57,7 +57,7 @@ A spawn/transport/RPC failure resolves `error` (or `aborted` if a cancel was req ## Environment scrub -The child env is built by [`buildChildEnv` from `@deepseek-ai/dsh-subagent-process`](../subagent-process/README.md) — the ambient env minus credential-shaped vars, with `config.env` layered on top after the scrub; the pattern and full semantics live there. For this backend that means the parent harness's own secrets never leak into the spawned agent implicitly, while the child's OWN `DEEPSEEK_API_KEY` is supplied deliberately via `config.env` and survives. +The child env is built by [`buildChildEnv` from `@deepseek-ai/dsh-subagent-subprocess`](../subagent-subprocess/README.md) — the ambient env minus credential-shaped vars, with `config.env` layered on top after the scrub; the pattern and full semantics live there. For this backend that means the parent harness's own secrets never leak into the spawned agent implicitly, while the child's OWN `DEEPSEEK_API_KEY` is supplied deliberately via `config.env` and survives. ## Testing diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json index 45fc6b072c..e73d861a79 100644 --- a/packages/subagent/subagent-acp/package.json +++ b/packages/subagent/subagent-acp/package.json @@ -25,7 +25,7 @@ "@deepseek-ai/dsh-agent": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-subagent": "^0.0.1", - "@deepseek-ai/dsh-subagent-process": "^0.0.1", + "@deepseek-ai/dsh-subagent-subprocess": "^0.0.1", "cordis": "^4.0.0-rc.6" }, "dependencies": { @@ -36,7 +36,7 @@ "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", - "@deepseek-ai/dsh-subagent-process": "workspace:^", + "@deepseek-ai/dsh-subagent-subprocess": "workspace:^", "@cordisjs/plugin-loader": "^1.0.0-rc.4", "cordis": "^4.0.0-rc.6" } diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts index a94c923f46..a9fefba27c 100644 --- a/packages/subagent/subagent-acp/src/run.ts +++ b/packages/subagent/subagent-acp/src/run.ts @@ -40,7 +40,7 @@ import { import { AgentId } from '@deepseek-ai/dsh-agent' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent' -import { buildChildEnv, disposeChildProcess, spawnFailure } from '@deepseek-ai/dsh-subagent-process' +import { buildChildEnv, disposeChildProcess, spawnFailure } from '@deepseek-ai/dsh-subagent-subprocess' /** * How the client answers a child's `session/request_permission`. The first cut diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index 6d351c71d0..92c025077a 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -6,7 +6,7 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' import SubagentService from '@deepseek-ai/dsh-subagent' -import { buildChildEnv, SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subagent-process' +import { buildChildEnv, SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subagent-subprocess' import type { Agent } from '@deepseek-ai/dsh-agent' import * as acp from '../src/index.ts' import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, startAcpRun, toAcpPrompt, type AcpRunSpec } from '../src/run.ts' diff --git a/packages/subagent/subagent-acp/tsconfig.json b/packages/subagent/subagent-acp/tsconfig.json index ab24f60f93..e415ace1de 100644 --- a/packages/subagent/subagent-acp/tsconfig.json +++ b/packages/subagent/subagent-acp/tsconfig.json @@ -27,7 +27,7 @@ "path": "../subagent" }, { - "path": "../subagent-process" + "path": "../subagent-subprocess" } ] } diff --git a/packages/subagent/subagent-process/README.md b/packages/subagent/subagent-subprocess/README.md similarity index 86% rename from packages/subagent/subagent-process/README.md rename to packages/subagent/subagent-subprocess/README.md index e6c8e10a96..ccc68bf31b 100644 --- a/packages/subagent/subagent-process/README.md +++ b/packages/subagent/subagent-subprocess/README.md @@ -1,4 +1,4 @@ -# @deepseek-ai/dsh-subagent-process +# @deepseek-ai/dsh-subagent-subprocess Shared machinery for **out-of-process subagent backends** — providers that spawn an external agent as a child process, such as the [ACP backend](../subagent-acp/README.md). A pure library (no provider, no registration, no Config): what every spawn-a-CLI-child backend needs to keep the parent deployment's credentials out of the child, tear the child down to quiescence, and isolate it from the host user's on-disk CLI state. Design rationale: [the Claude Code / Codex subagent backends RFC](../../../docs/rfc/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md). @@ -37,4 +37,4 @@ A per-run isolated config directory for an external CLI child (the target of `CL ## Testing -`tests/subagent-process.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end. +`tests/subagent-subprocess.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end. diff --git a/packages/subagent/subagent-process/package.json b/packages/subagent/subagent-subprocess/package.json similarity index 93% rename from packages/subagent/subagent-process/package.json rename to packages/subagent/subagent-subprocess/package.json index 218276be44..68f525dd8e 100644 --- a/packages/subagent/subagent-process/package.json +++ b/packages/subagent/subagent-subprocess/package.json @@ -1,5 +1,5 @@ { - "name": "@deepseek-ai/dsh-subagent-process", + "name": "@deepseek-ai/dsh-subagent-subprocess", "description": "Shared out-of-process subagent machinery: credential env scrub, spawn-failure capture, child-exit waits, the EOF-to-SIGTERM-to-SIGKILL dispose ladder, and isolated config dirs (pure lib; registers nothing)", "version": "0.0.1", "private": true, diff --git a/packages/subagent/subagent-process/src/index.ts b/packages/subagent/subagent-subprocess/src/index.ts similarity index 99% rename from packages/subagent/subagent-process/src/index.ts rename to packages/subagent/subagent-subprocess/src/index.ts index 219ed6b083..35d7383456 100644 --- a/packages/subagent/subagent-process/src/index.ts +++ b/packages/subagent/subagent-subprocess/src/index.ts @@ -15,7 +15,7 @@ * periods, a pinned config dir — is a PARAMETER here: defaults belong in each * consuming plugin's Config, per the no-hardcoded-tunables rule. * - * @module @deepseek-ai/dsh-subagent-process + * @module @deepseek-ai/dsh-subagent-subprocess */ import type { ChildProcess } from 'node:child_process' diff --git a/packages/subagent/subagent-process/tests/subagent-process.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts similarity index 94% rename from packages/subagent/subagent-process/tests/subagent-process.spec.ts rename to packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index d23f075284..2766ed0a41 100644 --- a/packages/subagent/subagent-process/tests/subagent-process.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -256,9 +256,9 @@ describe('disposeChildProcess', () => { describe('createIsolatedConfigDir', () => { it('creates a fresh private mkdtemp dir under the OS temp root', async () => { - const dir = await createIsolatedConfigDir('dsh-subagent-process-test-') + const dir = await createIsolatedConfigDir('dsh-subagent-subprocess-test-') try { - expect(dir.path.startsWith(join(tmpdir(), 'dsh-subagent-process-test-'))).toBe(true) + expect(dir.path.startsWith(join(tmpdir(), 'dsh-subagent-subprocess-test-'))).toBe(true) const st = await stat(dir.path) expect(st.isDirectory()).toBe(true) // Private (0700) per the defensive-patterns temp-dir rule. @@ -269,8 +269,8 @@ describe('createIsolatedConfigDir', () => { }) it('creates a distinct dir per call (per-run isolation)', async () => { - const a = await createIsolatedConfigDir('dsh-subagent-process-test-') - const b = await createIsolatedConfigDir('dsh-subagent-process-test-') + const a = await createIsolatedConfigDir('dsh-subagent-subprocess-test-') + const b = await createIsolatedConfigDir('dsh-subagent-subprocess-test-') try { expect(a.path).not.toBe(b.path) } finally { @@ -280,7 +280,7 @@ describe('createIsolatedConfigDir', () => { }) it('remove() deletes a fresh dir recursively and is idempotent', async () => { - const dir = await createIsolatedConfigDir('dsh-subagent-process-test-') + const dir = await createIsolatedConfigDir('dsh-subagent-subprocess-test-') await writeFile(join(dir.path, 'settings.json'), '{}') await dir.remove() expect(existsSync(dir.path)).toBe(false) @@ -289,7 +289,7 @@ describe('createIsolatedConfigDir', () => { }) it('returns a pinned dir verbatim and NEVER removes it', async () => { - const pinned = await mkdtemp(join(tmpdir(), 'dsh-subagent-process-pinned-')) + const pinned = await mkdtemp(join(tmpdir(), 'dsh-subagent-subprocess-pinned-')) try { const dir = await createIsolatedConfigDir('ignored-prefix-', pinned) expect(dir.path).toBe(pinned) @@ -302,7 +302,7 @@ describe('createIsolatedConfigDir', () => { }) it('does not create a missing pinned path (the deployment owns its lifecycle)', async () => { - const missing = join(tmpdir(), `dsh-subagent-process-missing-${process.pid}`) + const missing = join(tmpdir(), `dsh-subagent-subprocess-missing-${process.pid}`) const dir = await createIsolatedConfigDir('ignored-prefix-', missing) expect(dir.path).toBe(missing) expect(existsSync(missing)).toBe(false) @@ -311,7 +311,7 @@ describe('createIsolatedConfigDir', () => { }) it('remove() is best-effort: an rm rejection resolves instead of rejecting', async () => { - const dir = await createIsolatedConfigDir('dsh-subagent-process-locked-') + const dir = await createIsolatedConfigDir('dsh-subagent-subprocess-locked-') try { // The swallow contract is error-kind agnostic; EACCES stands in for the // family (EBUSY, a vanished mount, …) that best-effort must absorb. diff --git a/packages/subagent/subagent-process/tsconfig.json b/packages/subagent/subagent-subprocess/tsconfig.json similarity index 100% rename from packages/subagent/subagent-process/tsconfig.json rename to packages/subagent/subagent-subprocess/tsconfig.json diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 248405f643..023588835a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -635,9 +635,9 @@ importers: '@deepseek-ai/dsh-subagent': specifier: workspace:^ version: link:../subagent - '@deepseek-ai/dsh-subagent-process': + '@deepseek-ai/dsh-subagent-subprocess': specifier: workspace:^ - version: link:../subagent-process + version: link:../subagent-subprocess cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -715,12 +715,6 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) - packages/subagent/subagent-process: - devDependencies: - cordis: - specifier: ^4.0.0-rc.6 - version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) - packages/subagent/subagent-spawn: dependencies: schemastery: @@ -773,6 +767,12 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/subagent/subagent-subprocess: + devDependencies: + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/subagent/tool-subagent: dependencies: schemastery: diff --git a/tsconfig.build.json b/tsconfig.build.json index c5318e83fe..7fc770fac7 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -51,7 +51,7 @@ { "path": "./packages/support/subagent-mock" }, { "path": "./packages/subagent/tool-subagent" }, { "path": "./packages/subagent/subagent-inprocess" }, - { "path": "./packages/subagent/subagent-process" }, + { "path": "./packages/subagent/subagent-subprocess" }, { "path": "./packages/subagent/subagent-spawn" }, { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, diff --git a/tsconfig.json b/tsconfig.json index 8882714d50..380d5f72f5 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -62,7 +62,7 @@ { "path": "./packages/support/subagent-mock" }, { "path": "./packages/subagent/tool-subagent" }, { "path": "./packages/subagent/subagent-inprocess" }, - { "path": "./packages/subagent/subagent-process" }, + { "path": "./packages/subagent/subagent-subprocess" }, { "path": "./packages/subagent/subagent-spawn" }, { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, From 68ebc76af7a20e53744d1ca569e59014031ebe35 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:45:01 +0800 Subject: [PATCH 079/119] docs(rfc): the self-referential cordis toolset The design record for tool-cordis: the three-tool contract, the vm sandbox trust stance and boundary mechanisms, the dynamic-group lifecycle, cross-mount provide/inject composition, the generated runtime API catalog, and the alternatives weighed (per-capability registration tools, hand-maintained API tables, a mount provenance event, a hardened sandbox). --- docs/rfc/INDEX.md | 1 + ...6-07-08-self-referential-cordis-toolset.md | 84 +++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index e70e81877c..09f8caedb4 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -63,6 +63,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 | | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 | | [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 | +| [The self-referential cordis toolset](implemented/feature/2026-07-08-self-referential-cordis-toolset.md) | 2026-07-08 | ### Simplification diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md new file mode 100644 index 0000000000..95cb12b571 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -0,0 +1,84 @@ +# RFC: The self-referential cordis toolset + +Status: implemented + +## Problem + +Everything in this harness is a cordis plugin, but the agent running inside that plugin runtime cannot see or touch it: it cannot enumerate the services and events around it, cannot extend itself with a new tool mid-session, and cannot compose capabilities it invents. Handing the model that power is worth exploring — a self-referential agent that inspects and modifies its own runtime — but it raises three correctness problems at once, and the design is about answering them rather than the raw "let the model run code" mechanic. + +First, model-written registration must be validated where it happens: a malformed tool schema has to fail at registration, not when a later request tries to assemble it into a prompt. Second, model-written code has to call service APIs whose source it has never seen — guessed method signatures and, worse, guessed return-value shapes cost many steps of blind probing. Third, everything the model mounts must be fully disposable, by the model on demand and by the ordinary plugin lifecycle when the host plugin reloads, or a long session accretes orphaned listeners and tools. + +## Decision + +The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) — a new top-level `packages/cordis/` group — and is demoed by [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md). It gives the model three tools over the live cordis runtime it is running inside: inspect it, mount model-written plugins into it, dispose them again. + +The trust stance, stated once and threaded through the rest: the `node:vm` sandbox isolates the global context only — it prevents accidental global pollution, not malice. The `ctx` handed to a mounted plugin's `apply` is the real, fully privileged runtime handle; handing the model that handle is the point of the toolset. A deployment loads this plugin exactly as deliberately as it grants a bash tool — an opt-in capability in the app's `cordis.yml`, never a product default. + +### The three tools + +| Tool | Contract | +|---|---| +| `cordis_inspect` | Read-only report over the live runtime, one Markdown section per `what` value (omit `what` for all sections). Never mutates. | +| `cordis_mount` | Evaluates `code` (the body of an async JavaScript function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted as a child of the `cordis-dynamic` group fiber and tracked under a fresh id (`dyn-1`, `dyn-2`, …). | +| `cordis_unmount` | Disposes one dynamic mount by id and returns only after disposal reaches quiescence — every registration the plugin made is unwound, not merely requested to stop. | + +`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (the whole plugin fiber tree rebuilt from `ctx.registry`, ASCII, dynamic mounts annotated with their ids), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering. + +### Sandbox semantics + +Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through the fiber tree and disposable with it. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). + +Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. + +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **Guarded registration**: the `ctx` a mounted plugin receives is a proxy whose `tools.register` accepts only definitions returned by `harness.defineTool` (a marker symbol), so every dynamic tool passes SchemaSpec validation and realm normalization; everything else on `ctx` passes through with correct `this` binding, which is what keeps cross-mount `provide`/`inject` working. + +Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found): JSON Schema where the SchemaSpec DSL is expected gets a ✗/✓ example pair; an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. + +### The dynamic group and mount lifecycle + +Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself a child of the `tool-cordis` plugin's fiber. The group exists so the mounts form one subtree: they read as a unit in the inspect tree, and disposing `tool-cordis` (HMR reload, config unload) cascades over every mount through the ordinary parent→child fiber lifecycle — no bespoke cleanup. Mounting settles before it reports: the returned fiber is `await()`ed, and a startup error (a throwing `apply`, a duplicate tool name, a duplicate service) disposes the fiber and surfaces as the tool error, so a failed mount never lingers. A settled fiber that is not active is a legal pending mount — cordis semantics for unsatisfied `inject` — kept mounted and reported with what it waits for. Everything the plugin registers is an effect on its fiber, so `cordis_unmount` is nothing but an awaited `fiber.dispose()`. + +### Cross-mount composition via provide/inject + +Mounts relate to each other through ordinary cordis service semantics, with their ids as the lifecycle handles: mount A calls `ctx.provide('foo', value)`, mount B declares `inject: ['foo']` and activates the moment `foo` exists; mounted first, B stays pending and names the missing service; unmounting A sends B back to pending (its registrations unwound) and a later re-provide re-runs B's `apply` through the same guarded context; a duplicate provide fails loud with the owning fiber named. One realm caveat: a service value provided by a mount is a vm-realm object — method calls on it work from anywhere, but consumers must not assume host prototypes on it. + +### The generated API catalog + +`cordis_inspect what:"api"` and `what:"events"` answer from a machine-readable catalog generated at build time, never a hand-maintained table that would drift from the JSDoc it paraphrases. [`scripts/gen-cordis-api.ts`](../../../../scripts/gen-cordis-api.ts) reuses `collectServices` / `collectEvents` from [`scripts/gen-cordis-catalog.ts`](../../../../scripts/gen-cordis-catalog.ts) — the same AST walk that generates [the cordis service catalog](../../../cordis-catalog/services.md) and [events catalog](../../../cordis-catalog/events.md) — and emits `packages/cordis/tool-cordis/src/api-catalog.ts`, a committed, banner-commented data module. The artifact carries, per service, its key + one-line summary + raw method signatures; per event, name + `@mode` + signature + summary; the comment-stripped declarations of every exported type the service signatures reference (transitive closure — so a consumer sees that a bash run's `stdout` is `{ text, truncated }`, not a string); plus the curated inherited `ctx` surface shared with the cordis catalog generator. A type name declared in more than one package (each plugin's `Config`) is dropped as ambiguous, and an oversized declaration is truncated with a marker. + +Freshness is gated like every generated artifact: `pnpm run verify-cordis-api` (in `doc-sync`) regenerates in memory and fails on any diff, so a JSDoc edit that changes a public signature cannot ship without regenerating the catalog the model reads. At runtime the inspect tool intersects the catalog with the live runtime rather than dumping it: live catalogued services render summary + signatures, live services without a catalog entry (mount-provided ones) render name + owning fiber, catalogued services with no live provider are listed tersely, and the referenced type shapes follow. + +### Configuration, rendering, and observability + +The plugin exposes one config field, validated by schemastery and documented in [the config catalog](../../../config-catalog.md): `vmTimeoutMs` (default 5000), the millisecond bound on the synchronous portion of mount-code evaluation. Tool names, the `cordis-dynamic` group name, and the `dyn-` id prefix are structural vocabulary and stay fixed. All three tools render as `generic` cards per [the tool cookbook](../../../cookbook/adding-a-tool.md) (`cordis_inspect` a `read`, `cordis_mount` an `execute` carrying the code as `rawInput`, `cordis_unmount` a `delete`), with no `presentResult` overrides. + +Model-visible ⟺ logged holds with no new session event type: a mount or unmount is visible only through its own `tool/call` / `tool/result` pair, which the loop logs, and the changed tool set a mount induces is logged by the request-header delta the loop already emits when schemas change between steps. There is deliberately no `cordis/mount` provenance event — it would duplicate what the tool-call pair records. Dynamic mounts are process-lifetime, not session state: resuming a persisted session rehydrates the conversation but does not re-mount plugins. + +## Alternatives considered + +**A structured per-capability registration tool instead of `cordis_mount`.** The most tempting alternative is a `cordis_register_tool` with explicit `name` / `description` / `parameters` / `code` fields (and siblings `cordis_register_listener`, `cordis_register_service`, …) rather than a single "mount a plugin" primitive. It was rejected because its one real win — no plugin boilerplate for the single commonest case — does not pay for its costs, while a single mount primitive answers every capability at once. + +| Dimension | Structured per-capability tools | Single `cordis_mount` | +|---|---|---| +| Schema correctness | `parameters` is still a model-written JSON object needing SchemaSpec validation, merely one step earlier | The same validation runs at the sandbox boundary, with the same instructive errors | +| The code field | An `execute` body is still model-written JS in a vm; the realm and service-call correctness problems are unchanged | One sandbox, one normalization path, one guarded registration | +| Capability coverage | Tools only; listeners, services, `inject` relations each need another structured tool — a surface that grows without bound | One vocabulary (a cordis plugin) covers every effect, present and future | +| Cross-mount composition | Not expressible in a tool-registration payload | Native `provide`/`inject`, ordinary cordis semantics | +| Inspectability | Registers something the plugin tree cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders | +| Model ergonomics | Wins for the single most common case (no plugin boilerplate) | Mitigated by the canonical recipe in the mount description plus boundary errors that teach the fix | + +The correctness investment therefore goes where it pays for every capability at once: the generated API catalog surfaced through `cordis_inspect`, and sandbox-boundary validation whose error messages teach the correct call. A structured registration tool remains addable later as sugar that synthesizes mount code; nothing here forecloses it. + +**A hand-maintained service/event reference in the tool.** The first cut of the inspect tool carried a hand-written table of service method signatures. It was replaced by the generated `api-catalog.ts` because a hand table drifts from the JSDoc the moment a signature changes and nothing gates the drift, whereas the generated artifact is freshness-checked against the same AST the docs use. + +**A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a request-header delta, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call. + +**A hardened / capability-restricted sandbox.** Trapping Node built-ins might suggest an intent to sandbox for safety. It is explicitly not that: the traps redirect the model toward cordis services (and away from leak-prone Node timers) for correctness and inspectability, but `ctx` is fully privileged and the vm is not a security boundary. A real security boundary (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. + +## Consequences + +The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` vetoes the chain, so a mounted listener can lobotomize the agent's own tool dispatch ([waterfall semantics](../../../cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume. + +The instructive boundary errors were not guessed — they were written against a live self-design session in which a real model was asked to build itself coding tools. That session surfaced the failure modes now mitigated: the model closed a returned plugin object with `});` and got only a bare `Unexpected token ')'` it retried blind; it hit a false-positive "this is TypeScript" hint because a description string contained the word "as"; and, most costly, it guessed a bash run's `stdout` was a string and burned six steps building throwaway debug tools to discover it is `{ text, truncated }`. The fixes — source-line-plus-caret parse errors, line-scoped TypeScript detection, the type-shape closure in the API catalog, and the redirect traps — cut a second session from dozens of tool calls with repeated errors to a first-try success on every capability, including a model that hit a Node-`setTimeout` trap and self-corrected to `inject: ['timer']` in one step. + +Coverage is named per tier: package unit specs drive the three tools through a real `ToolRegistry` on a real fiber tree (the mount success/failure family, vm isolation, dual-realm `instanceof`, realm normalization against the real `isJsonValue`, the SchemaSpec and raw-registration rejections, the Node-API traps, the cross-mount provide/inject matrix, catalog-backed `api`/`events` rendering, config validation, presenters, quiescent unmount, and the HMR cascade), a `MockAdapter` loop test proves a tool mounted in one step is dispatchable in the next, and the example carries a keyless Loader smoke plus a with-key smoke that world-verifies a live model mounting a listener, building its own tool, and composing two mounts. No snapshot scenario is added: the toolset ships in no ACP-served app, so it changes no editor-facing transcript, and its presenters are unit-tested pure functions — adding it to the ACP example solely for a golden would rewrite the pinned request-header tool set of every recorded scenario. From ee1da1ce5be9dbee1c97080687355b471a1b4dad Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:45:46 +0800 Subject: [PATCH 080/119] =?UTF-8?q?feat(cordis):=20@deepseek-ai/dsh-tool-c?= =?UTF-8?q?ordis=20=E2=80=94=20inspect/mount/unmount=20over=20the=20live?= =?UTF-8?q?=20runtime?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New top-level packages/cordis/ group with the self-referential toolset: cordis_inspect (services / plugin tree / tools / dynamic mounts / api / events, the api section intersecting the generated catalog with the live service store), cordis_mount (model-written code evaluated in a node:vm sandbox, mounted under one cordis-dynamic group fiber as dyn-), cordis_unmount (awaited disposal to quiescence). Boundary mechanisms: dual-realm instanceof, JSON realm normalization of dynamic tool results, marker-guarded registration, SchemaSpec teaching errors, parse failures surfaced with the offending line + caret and a line-scoped TypeScript hint, and the unmount-first recipe on tool-name collisions. Config: vmTimeoutMs (schemastery, default 5000). Design record: docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. The tool-catalog boot manifest, its regenerated output, and the pinned tool-name list land here rather than with the other repo registration: the completeness guard globs packages/*/tool-* and fails the generator (and the core/tools spec) the moment the package directory exists. --- docs/tool-catalog.md | 73 ++ packages/cordis/README.md | 7 + packages/cordis/tool-cordis/README.md | 33 + packages/cordis/tool-cordis/package.json | 42 + .../cordis/tool-cordis/src/api-catalog.ts | 786 ++++++++++++++++++ .../cordis/tool-cordis/src/fiber-state.ts | 39 + packages/cordis/tool-cordis/src/guard.ts | 199 +++++ packages/cordis/tool-cordis/src/index.ts | 228 +++++ packages/cordis/tool-cordis/src/inspect.ts | 225 +++++ packages/cordis/tool-cordis/src/mount.ts | 64 ++ packages/cordis/tool-cordis/src/present.ts | 51 ++ packages/cordis/tool-cordis/src/sandbox.ts | 153 ++++ .../tool-cordis/tests/cross-mount.spec.ts | 105 +++ packages/cordis/tool-cordis/tests/helpers.ts | 104 +++ .../cordis/tool-cordis/tests/inspect.spec.ts | 123 +++ .../tool-cordis/tests/integration.spec.ts | 74 ++ .../cordis/tool-cordis/tests/mount.spec.ts | 409 +++++++++ .../cordis/tool-cordis/tests/present.spec.ts | 41 + .../tool-cordis/tests/tool-cordis.spec.ts | 49 ++ .../tool-cordis/tests/unmount-hmr.spec.ts | 82 ++ packages/cordis/tool-cordis/tsconfig.json | 27 + .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- pnpm-lock.yaml | 34 + scripts/gen-tool-catalog.ts | 13 + tsconfig.base.json | 1 + tsconfig.build.json | 1 + tsconfig.json | 1 + 27 files changed, 2965 insertions(+), 1 deletion(-) create mode 100644 packages/cordis/README.md create mode 100644 packages/cordis/tool-cordis/README.md create mode 100644 packages/cordis/tool-cordis/package.json create mode 100644 packages/cordis/tool-cordis/src/api-catalog.ts create mode 100644 packages/cordis/tool-cordis/src/fiber-state.ts create mode 100644 packages/cordis/tool-cordis/src/guard.ts create mode 100644 packages/cordis/tool-cordis/src/index.ts create mode 100644 packages/cordis/tool-cordis/src/inspect.ts create mode 100644 packages/cordis/tool-cordis/src/mount.ts create mode 100644 packages/cordis/tool-cordis/src/present.ts create mode 100644 packages/cordis/tool-cordis/src/sandbox.ts create mode 100644 packages/cordis/tool-cordis/tests/cross-mount.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/helpers.ts create mode 100644 packages/cordis/tool-cordis/tests/inspect.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/integration.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/mount.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/present.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/tool-cordis.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts create mode 100644 packages/cordis/tool-cordis/tsconfig.json diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 3645ff40e9..e77716f736 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -16,6 +16,7 @@ This table connects model-visible tool names to the plugin package and service s | Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note | | --- | --- | --- | --- | --- | --- | | `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. | +| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. | | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. | @@ -105,6 +106,78 @@ Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/ The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. +## `@deepseek-ai/dsh-tool-cordis` + +### `cordis_inspect` + +Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — dynamic mounts appear under the `cordis-dynamic` group with their ids), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. + +```json +{ + "type": "object", + "properties": { + "what": { + "type": "string", + "description": "Limit the report to one section. Omit for all sections.", + "enum": [ + "services", + "plugins", + "tools", + "dynamic", + "api", + "events" + ] + } + } +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) + +### `cordis_mount` + +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`; there is no `require`, `process`, `Buffer`, or network. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. + +```json +{ + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "Body of an async JS function; must `return` the plugin to mount." + } + }, + "required": [ + "code" + ] +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) + +### `cordis_unmount` + +Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")." + } + }, + "required": [ + "id" + ] +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) + +Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. + ## `@deepseek-ai/dsh-tool-fs` ### `edit` diff --git a/packages/cordis/README.md b/packages/cordis/README.md new file mode 100644 index 0000000000..2eb33006e5 --- /dev/null +++ b/packages/cordis/README.md @@ -0,0 +1,7 @@ +# packages/cordis — the self-referential runtime toolset + +Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the plugin tree and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). + +| Package | Role | ctx key | +|---|---|---| +| [`tool-cordis/`](tool-cordis/README.md) | The `cordis_inspect` / `cordis_mount` / `cordis_unmount` tools: read the runtime, evaluate model-written plugin code in a `node:vm` sandbox, and manage the dynamic mounts under one group fiber | registers on `ctx.tools` | diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md new file mode 100644 index 0000000000..71b79fecad --- /dev/null +++ b/packages/cordis/tool-cordis/README.md @@ -0,0 +1,33 @@ +# @deepseek-ai/dsh-tool-cordis + +The self-referential cordis toolset: three model-facing tools over the live runtime the agent runs inside. Design home — sandbox semantics, mount lifecycle, cross-mount composition, the generated API catalog, standing decisions: [the toolset RFC](../../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). + +## What it does + +- `cordis_inspect` — read-only report over the runtime: services, the plugin fiber tree (ASCII), registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. +- `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-`. +- `cordis_unmount` — disposes one mount by id, returning only after quiescence. + +Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-catalog.md). + +## Trust stance + +The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is the real, fully privileged runtime handle; load this plugin as deliberately as you would grant a bash tool. + +## Config + +| Field | Default | Meaning | +|---|---|---| +| `vmTimeoutMs` | `5000` | Bound on the SYNCHRONOUS portion of mount-code evaluation; an async body escapes it | + +## The generated API catalog + +`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time. + +## Rendering + +All three tools render `generic` cards (`read` / `execute` / `delete`); `cordis_mount` carries the mount code as `rawInput`. Presenters are pure functions of the args; results keep the default text rendering. + +## Export shape + +Namespace plugin: named exports `name` / `inject` / `Config` / `apply`, no default export ([docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)). diff --git a/packages/cordis/tool-cordis/package.json b/packages/cordis/tool-cordis/package.json new file mode 100644 index 0000000000..657013f1c4 --- /dev/null +++ b/packages/cordis/tool-cordis/package.json @@ -0,0 +1,42 @@ +{ + "name": "@deepseek-ai/dsh-tool-cordis", + "description": "Self-referential cordis toolset: inspect the live runtime, mount and dispose model-written plugins", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-tools": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "@cordisjs/plugin-loader": "^1.0.0-rc.4", + "cordis": "^4.0.0-rc.6", + "@cordisjs/plugin-timer": "workspace:^" + } +} diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts new file mode 100644 index 0000000000..39f1a12f47 --- /dev/null +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -0,0 +1,786 @@ +/** + * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run + * `pnpm run gen-cordis-api` to regenerate (freshness-gated by + * `pnpm run verify-cordis-api` in doc-sync). + * + * The machine-readable cordis API catalog `cordis_inspect` serves to the + * model: harness services (summary + public method signatures), harness + * events (mode + signature), and the inherited `ctx` surface. Produced by + * the same AST walk as docs/cordis-catalog, so this data and the rendered + * docs cannot diverge. + * + * @module @deepseek-ai/dsh-tool-cordis/api-catalog + */ + +/** One harness `ctx.` service: its one-line summary and public method signatures. */ +export interface ServiceApiEntry { + /** The `ctx.` name, e.g. `tools`. */ + key: string + /** First sentence of the service class JSDoc. */ + summary: string + /** Public method signatures, bodies stripped, in source order. */ + methods: readonly string[] +} + +/** One harness event: its dispatch mode, exact signature, and one-line summary. */ +export interface EventApiEntry { + /** The scoped event name, e.g. `agent/status`. */ + name: string + /** The dispatch mode from the declaration's `@mode` tag. */ + mode: string + /** The exact listener signature, whitespace-normalized. */ + signature: string + /** First sentence of the event JSDoc. */ + summary: string +} + +/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */ +export interface InheritedApiEntry { + /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */ + name: string + /** One-line summary of what the member does. */ + summary: string +} + +/** One named type shape the service signatures reference. */ +export interface TypeApiEntry { + /** The exported type/interface name, e.g. `BashRunResult`. */ + name: string + /** The full declaration text, comments stripped. */ + declaration: string +} + +/** Every harness `ctx.` service, sorted by key. */ +export const SERVICE_API: readonly ServiceApiEntry[] = [ + { + key: 'agentLoop', + summary: 'The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`.', + methods: [ + 'create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent', + 'createAgent(options: CreateAgentOptions): AgentHandle', + 'async resume(options: ResumeAgentOptions): Promise', + ], + }, + { + key: 'agents', + summary: 'Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package.', + methods: [ + 'setFactory(factory: AgentFactory): () => void', + 'create(options: CreateAgentOptions): AgentHandle', + 'async resume(options: ResumeAgentOptions): Promise', + 'register(agent: Agent): () => void', + 'get(id: AgentId): Agent | undefined', + 'list(): Agent[]', + ], + }, + { + key: 'bash', + summary: 'Abstract bash execution service.', + methods: [ + 'abstract resolve(request: BashExecRequest): BashExecSpec', + 'abstract run(spec: BashExecSpec): Promise', + 'abstract start(spec: BashExecSpec): BashTask', + 'abstract get(id: BashTaskId): BashTask | undefined', + 'abstract ownerOf(id: BashTaskId): OwnerToken | undefined', + 'abstract list(): BashTask[]', + 'abstract readOutput(id: BashTaskId): BashTaskRead', + 'abstract kill(id: BashTaskId): boolean', + 'onTaskDone(listener: BashTaskListener): () => void', + ], + }, + { + key: 'compact', + summary: 'Abstract compaction service.', + methods: [ + 'abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, signal: AbortSignal, ): Promise', + 'abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise', + ], + }, + { + key: 'fs', + summary: 'Abstract filesystem provider service.', + methods: [ + 'abstract resolve(path: string, opts?: { cwd?: string }): Promise', + 'abstract stat(target: FsTarget, signal?: AbortSignal): Promise', + 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise', + 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise>', + 'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise', + 'abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise', + 'abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise', + ], + }, + { + key: 'llm', + summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.', + methods: [ + 'registerAdapter(models: string[], adapter: LlmAdapter): () => void', + 'models(): string[]', + 'stream(options: GenerateOptions): AsyncIterable', + ], + }, + { + key: 'sessionPersistence', + summary: 'Abstract durable session-persistence service.', + methods: [ + 'abstract create(meta: SessionHeader): Promise', + 'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise', + 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>', + 'abstract list(): Promise', + ], + }, + { + key: 'sessions', + summary: 'In-memory session store (`ctx.sessions`).', + methods: [ + 'create(id?: SessionId, options?: CreateSessionOptions): Session', + 'prepare(id?: SessionId, options?: CreateSessionOptions): Session', + 'enter(session: Session): () => void', + 'announce(session: Session): void', + 'get(id: SessionId): Session | undefined', + 'list(): Session[]', + 'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session', + ], + }, + { + key: 'subagents', + summary: 'The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.', + methods: [ + 'registerProvider(provider: SubagentProvider): () => void', + 'getProvider(name: string): SubagentProvider | undefined', + 'list(): string[]', + 'start(name: string, request: SubagentStartRequest): SubagentRun', + ], + }, + { + key: 'systemPrompt', + summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.', + methods: [ + 'section(section: PromptSection): () => void', + 'tools(provider: () => ToolSchema[]): () => void', + 'variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void', + 'async assemble(context: AssembleContext = {}): Promise', + ], + }, + { + key: 'tools', + summary: 'Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → `tools/execute` → `tools/post-execute` pipeline.', + methods: [ + 'register(definition: ToolDefinition): () => void', + 'get(name: string): ToolDefinition | undefined', + 'schemas(): ToolSchema[]', + 'async execute(exec: ToolExecution): Promise', + ], + }, + { + key: 'web', + summary: 'The web access service.', + methods: [ + 'registerSearchProvider(provider: WebSearchProvider): () => void', + 'registerFetchProvider(provider: WebFetchProvider): () => void', + 'async search(request: WebSearchRequest, exec?: WebExecContext): Promise', + 'async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise', + ], + }, +] + +/** Every harness event, sorted by name. */ +export const EVENT_API: readonly EventApiEntry[] = [ + { + name: 'agent/created', + mode: 'emit', + signature: '\'agent/created\'(agent: Agent): void', + summary: 'An agent was registered in the AgentRegistry and is ready to receive messages.', + }, + { + name: 'agent/disposed', + mode: 'emit', + signature: '\'agent/disposed\'(agent: Agent): void', + summary: 'An agent was disposed and removed from the registry; its fiber and any in-flight turn have been torn down.', + }, + { + name: 'agent/error', + mode: 'emit', + signature: '\'agent/error\'(agent: Agent, turn: number, step: number, error: Error): void', + summary: 'A step or turn errored.', + }, + { + name: 'agent/pre-step', + mode: 'serial', + signature: '\'agent/pre-step\'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal): Promise | void', + summary: 'Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step\'s `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`.', + }, + { + name: 'agent/prompt-submit', + mode: 'waterfall', + signature: '\'agent/prompt-submit\'(agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise): Promise', + summary: 'Waterfall: decide what happens to ONE drained queued message before it becomes a `user/message` — allow (optionally rewriting the prompt bytes or attaching `additionalContext`) or block it.', + }, + { + name: 'agent/queued', + mode: 'emit', + signature: '\'agent/queued\'(agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void', + summary: 'A message entered the agent\'s inbox (queued or steering).', + }, + { + name: 'agent/request', + mode: 'waterfall', + signature: '\'agent/request\'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise', + summary: 'Waterfall: shape the step\'s call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use).', + }, + { + name: 'agent/session-start', + mode: 'emit', + signature: '\'agent/session-start\'(agent: Agent, source: SessionStartSource): void', + summary: 'The agent\'s session lifecycle began, fired once before its first turn.', + }, + { + name: 'agent/status', + mode: 'emit', + signature: '\'agent/status\'(agent: Agent, status: AgentStatus): void', + summary: 'Agent status changed (`idle` ⇄ `running`, or → `disposed`).', + }, + { + name: 'agent/step-result', + mode: 'waterfall', + signature: '\'agent/step-result\'(agent: Agent, turn: number, step: number, message: Message, next: () => Promise): Promise', + summary: 'Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …).', + }, + { + name: 'agent/turn-continuation', + mode: 'waterfall', + signature: '\'agent/turn-continuation\'(agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise', + summary: 'Waterfall: override the turn-continuation decision via a typed ContinuationDecision.', + }, + { + name: 'fs/edit-intent', + mode: 'waterfall', + signature: '\'fs/edit-intent\'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>', + summary: 'Single-slot decision: produce the optional version guard for the next FileSystem.editText.', + }, + { + name: 'fs/observed', + mode: 'emit', + signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void', + summary: 'Record that an actor observed a target at a version, after a successful read/write/edit.', + }, + { + name: 'fs/write-intent', + mode: 'waterfall', + signature: '\'fs/write-intent\'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise): Promise', + summary: 'Single-slot decision: produce the write intent for the next FileSystem.writeText.', + }, + { + name: 'llm/stream', + mode: 'waterfall', + signature: '\'llm/stream\'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable): AsyncIterable', + summary: 'Waterfall around every streaming model call (retry, replay, routing).', + }, + { + name: 'session/created', + mode: 'emit', + signature: '\'session/created\'(session: Session): void', + summary: 'A session was created in the store.', + }, + { + name: 'session/event', + mode: 'emit', + signature: '\'session/event\'(session: Session, event: SessionEvent): void', + summary: 'An event was appended to a session log (sync, fire-and-forget).', + }, + { + name: 'session/flush', + mode: 'parallel', + signature: '\'session/flush\'(session: Session): Promise | void', + summary: 'Awaited durability checkpoint.', + }, + { + name: 'subagent/end', + mode: 'emit', + signature: '\'subagent/end\'(info: SubagentRunEndInfo): void', + summary: 'A subagent run settled — emitted when SubagentRun.result resolves (any stop reason).', + }, + { + name: 'subagent/provider-added', + mode: 'emit', + signature: '\'subagent/provider-added\'(provider: SubagentProvider): void', + summary: 'A provider became resolvable in the SubagentService registry.', + }, + { + name: 'subagent/provider-removed', + mode: 'emit', + signature: '\'subagent/provider-removed\'(name: string): void', + summary: 'A provider left the registry (its plugin\'s fiber was disposed — an unload or an HMR reload).', + }, + { + name: 'subagent/start', + mode: 'emit', + signature: '\'subagent/start\'(info: SubagentRunInfo): void', + summary: 'A subagent run started — emitted after the provider is resolved and its capabilities validated, as the child run begins.', + }, + { + name: 'system-prompt/assemble', + mode: 'waterfall', + signature: '\'system-prompt/assemble\'(this: SystemPrompt, assembly: PromptAssembly, context: AssembleContext, next: () => Promise): Promise', + summary: 'Waterfall around prompt assembly — mutate or extend the PromptAssembly (sections + tools + variables) before it is rendered.', + }, + { + name: 'system-prompt/change', + mode: 'emit', + signature: '\'system-prompt/change\'(): void', + summary: 'A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed).', + }, + { + name: 'tools/change', + mode: 'emit', + signature: '\'tools/change\'(): void', + summary: 'A tool was registered or unregistered (the available tool set changed).', + }, + { + name: 'tools/execute', + mode: 'waterfall', + signature: '\'tools/execute\'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise', + summary: 'Around-dispatch waterfall wrapping the registry\'s core tool dispatch, between the `tools/pre-execute` gate and the `tools/post-execute` seam.', + }, + { + name: 'tools/post-execute', + mode: 'waterfall', + signature: '\'tools/post-execute\'(this: ToolRegistry, exec: ToolExecution, result: ToolExecutionResult, next: () => Promise): Promise', + summary: 'Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code\'s `PostToolUse`).', + }, + { + name: 'tools/pre-execute', + mode: 'waterfall', + signature: '\'tools/pre-execute\'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise', + summary: 'Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code\'s `PreToolUse`).', + }, +] + +/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */ +export const TYPE_API: readonly TypeApiEntry[] = [ + { + name: 'Agent', + declaration: 'export interface Agent {\n readonly id: AgentId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n send(content: ContentBlock[], options?: SendOptions): void;\n steer(content: ContentBlock[], options?: SendOptions): void;\n inject(content: ContentBlock[], options?: SendOptions): void;\n cancel(reason?: string): void;\n whenIdle(): Promise;\n}', + }, + { + name: 'AgentFactory', + declaration: 'export interface AgentFactory {\n createAgent(options: CreateAgentOptions): AgentHandle;\n resume(options: ResumeAgentOptions): Promise;\n}', + }, + { + name: 'AgentHandle', + declaration: 'export interface AgentHandle {\n agent: Agent;\n dispose(): Promise;\n}', + }, + { + name: 'AgentId', + declaration: 'export type AgentId = Branded<\'AgentId\'>;', + }, + { + name: 'AgentOptions', + declaration: 'export interface AgentOptions {\n model?: string;\n}', + }, + { + name: 'AgentStatus', + declaration: 'export type AgentStatus = \'idle\' | \'running\' | \'disposed\';', + }, + { + name: 'AssembleContext', + declaration: 'export interface AssembleContext {\n}', + }, + { + name: 'AssembledSection', + declaration: 'export interface AssembledSection {\n name: string;\n order: number;\n text: string;\n}', + }, + { + name: 'BashExecRequest', + declaration: 'export interface BashExecRequest {\n command: string;\n workdir?: string | undefined;\n timeoutMs?: number | undefined;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner?: OwnerToken | undefined;\n}', + }, + { + name: 'BashExecSpec', + declaration: 'export interface BashExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner: OwnerToken | undefined;\n}', + }, + { + name: 'BashRunResult', + declaration: 'export interface BashRunResult {\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: CollectedOutput;\n stderr: CollectedOutput;\n}', + }, + { + name: 'BashTask', + declaration: 'export interface BashTask {\n readonly id: BashTaskId;\n readonly command: string;\n status: BashTaskStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n}', + }, + { + name: 'BashTaskId', + declaration: 'export type BashTaskId = Branded<\'BashTaskId\'>;', + }, + { + name: 'BashTaskListener', + declaration: 'export type BashTaskListener = (task: BashTask) => void;', + }, + { + name: 'BashTaskRead', + declaration: 'export interface BashTaskRead {\n task: BashTask;\n delta: string;\n lossy: boolean;\n stdoutSpillPath?: string;\n stderrSpillPath?: string;\n}', + }, + { + name: 'BashTaskStatus', + declaration: 'export type BashTaskStatus = \'running\' | \'completed\' | \'killed\';', + }, + { + name: 'Branded', + declaration: 'export type Branded = string & {\n readonly [BRAND]: B;\n};', + }, + { + name: 'CallId', + declaration: 'export type CallId = Branded<\'CallId\'>;', + }, + { + name: 'CollectedOutput', + declaration: 'export interface CollectedOutput {\n text: string;\n truncated: boolean;\n spillPath?: string;\n}', + }, + { + name: 'CompactAgentContext', + declaration: 'export interface CompactAgentContext {\n session: Session;\n options: {\n model?: string;\n };\n}', + }, + { + name: 'CompactionResult', + declaration: 'export interface CompactionResult {\n startSeq: number;\n summarySeq: number;\n endSeq: number;\n summary: ContentBlock[];\n shadowedRange: {\n start: number;\n end: number;\n };\n shadowedSeqs: number[];\n shadowedTokenCount: number;\n}', + }, + { + name: 'ContentBlockMap', + declaration: 'export interface ContentBlockMap {\n \'text\': TextBlock;\n \'reasoning\': ReasoningBlock;\n \'tool-call\': ToolCallBlock;\n \'tool-result\': ToolResultBlock;\n}', + }, + { + name: 'ContentBlockType', + declaration: 'export type ContentBlockType = keyof ContentBlockMap;', + }, + { + name: 'CreateAgentOptions', + declaration: 'export interface CreateAgentOptions {\n agentId: AgentId;\n sessionId: SessionId;\n meta?: {\n cwd?: string;\n parentSession?: SessionId;\n seedLength?: number;\n };\n seed?: SessionEvent[];\n agentOptions?: AgentOptions;\n}', + }, + { + name: 'CreateSessionOptions', + declaration: 'export interface CreateSessionOptions {\n seed?: SessionEvent[];\n meta?: {\n cwd?: string;\n parentSession?: SessionId;\n createdAt?: number;\n seedLength?: number;\n };\n}', + }, + { + name: 'DiffCallView', + declaration: 'export interface DiffCallView {\n card: \'diff\';\n title: string;\n diffs: FileDiff[];\n locations?: FileLocation[];\n}', + }, + { + name: 'DiffResultView', + declaration: 'export interface DiffResultView {\n card: \'diff\';\n title?: string;\n diffs: FileDiff[];\n}', + }, + { + name: 'FileDiff', + declaration: 'export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n}', + }, + { + name: 'FileLocation', + declaration: 'export interface FileLocation {\n path: string;\n line?: number;\n}', + }, + { + name: 'FinishReason', + declaration: 'export type FinishReason = FinishReasonMap[keyof FinishReasonMap];', + }, + { + name: 'FinishReasonMap', + declaration: 'export interface FinishReasonMap {\n \'stop\': {\n kind: \'stop\';\n };\n \'tool-calls\': {\n kind: \'tool-calls\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n \'aborted\': {\n kind: \'aborted\';\n };\n \'error\': {\n kind: \'error\';\n message: string;\n code?: string;\n };\n}', + }, + { + name: 'FsDirEntry', + declaration: 'export interface FsDirEntry {\n name: string;\n type: \'file\' | \'directory\' | \'other\';\n target: FsTarget;\n version?: FsVersion;\n size?: number;\n}', + }, + { + name: 'FsEditOutcome', + declaration: 'export interface FsEditOutcome {\n version: FsVersion;\n before: string;\n after: string;\n}', + }, + { + name: 'FsEditRequest', + declaration: 'export interface FsEditRequest {\n oldString: string;\n newString: string;\n replaceAll: boolean;\n}', + }, + { + name: 'FsInfo', + declaration: 'export interface FsInfo {\n version: FsVersion;\n type: \'file\' | \'directory\' | \'other\';\n size?: number;\n}', + }, + { + name: 'FsTarget', + declaration: 'export interface FsTarget {\n targetKey: FsTargetKey;\n displayPath: string;\n}', + }, + { + name: 'FsTargetKey', + declaration: 'export type FsTargetKey = Branded<\'FsTargetKey\'>;', + }, + { + name: 'FsVersion', + declaration: 'export type FsVersion = Branded<\'FsVersion\'>;', + }, + { + name: 'FsWriteIntent', + declaration: 'export type FsWriteIntent = {\n kind: \'createIfAbsent\';\n} | {\n kind: \'replaceIfVersion\';\n version: FsVersion;\n};', + }, + { + name: 'FsWriteOutcome', + declaration: 'export interface FsWriteOutcome {\n operation: \'create\' | \'update\';\n version: FsVersion;\n before: string | null;\n after: string;\n}', + }, + { + name: 'GenerateOptions', + declaration: 'export interface GenerateOptions {\n model: string;\n messages: Message[];\n system?: string;\n tools?: ToolSchema[];\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n signal?: AbortSignal;\n sessionId?: Branded<\'SessionId\'>;\n}', + }, + { + name: 'GenericCallView', + declaration: 'export interface GenericCallView {\n card: \'generic\';\n title: string;\n kind?: ToolCallKind;\n rawInput?: unknown;\n content?: ContentBlock[];\n locations?: FileLocation[];\n}', + }, + { + name: 'GenericResultView', + declaration: 'export interface GenericResultView {\n card: \'generic\';\n title?: string;\n content?: ContentBlock[];\n}', + }, + { + name: 'HookContext', + declaration: 'export interface HookContext {\n content: ContentBlock[];\n source: MessageSource;\n}', + }, + { + name: 'Message', + declaration: 'export interface Message {\n role: \'system\' | \'user\' | \'assistant\';\n content: ContentBlock[];\n}', + }, + { + name: 'MessageSource', + declaration: 'export type MessageSource = MessageSourceMap[keyof MessageSourceMap];', + }, + { + name: 'MessageSourceMap', + declaration: 'export interface MessageSourceMap {\n user: {\n kind: \'user\';\n };\n plugin: {\n kind: \'plugin\';\n plugin: string;\n };\n}', + }, + { + name: 'OwnerToken', + declaration: 'export type OwnerToken = Branded<\'OwnerToken\'>;', + }, + { + name: 'PromptAssembly', + declaration: 'export interface PromptAssembly {\n sections: AssembledSection[];\n tools: ToolSchema[];\n variables: Record;\n}', + }, + { + name: 'PromptSection', + declaration: 'export interface PromptSection {\n name: string;\n order: number;\n text: string | ((context: AssembleContext) => string);\n}', + }, + { + name: 'ReasoningBlock', + declaration: 'export interface ReasoningBlock {\n type: \'reasoning\';\n text: string;\n}', + }, + { + name: 'ResumeAgentOptions', + declaration: 'export interface ResumeAgentOptions {\n agentId: AgentId;\n resumeSessionId: SessionId;\n agentOptions?: AgentOptions;\n}', + }, + { + name: 'SendOptions', + declaration: 'export interface SendOptions {\n source?: MessageSource;\n}', + }, + { + name: 'SessionEvent', + declaration: 'export type SessionEvent = {\n [K in SessionEventType]: {\n type: K;\n seq: number;\n time: number;\n data: SessionEventMap[K];\n } & (K extends SurfaceEventType ? {\n sourceEventSeqs?: number[];\n surfaceOp?: SurfaceOp;\n } : object);\n}[T];', + }, + { + name: 'SessionEventMap', + declaration: 'export interface SessionEventMap {\n \'turn/start\': {\n turn: number;\n trigger: TurnTrigger;\n };\n \'turn/end\': {\n turn: number;\n reason: TurnEndReason;\n };\n \'step/start\': {\n turn: number;\n step: number;\n };\n \'step/end\': {\n turn: number;\n step: number;\n };\n \'user/message\': {\n content: ContentBlock[];\n source: MessageSource;\n };\n \'prompt/blocked\': {\n content: ContentBlock[];\n source: MessageSource;\n reason: string;\n };\n \'context/message\': {\n content: ContentBlock[];\n source: MessageSource;\n };\n \'assistant/chunk\': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n \'assistant/message\': {\n turn: number;\n step: number;\n content: ContentBlock[];\n usage?: TokenUsage;\n };\n \'tool/call\': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n \'tool/result\': {\n turn: number;\n step: number;\n callId: CallId;\n content: ContentBlock[];\n isError: boolean;\n error?: {\n name: string;\n code: string;\n };\n meta?: unknown;\n };\n \'steering/message\': {\n turn: number;\n content: ContentBlock[];\n source: MessageSource;\n };\n \'todo/write\': {\n todos: TodoItem[];\n };\n \'request/header\': {\n header: E /* …truncated — full shape in source */', + }, + { + name: 'SessionEventType', + declaration: 'export type SessionEventType = keyof SessionEventMap;', + }, + { + name: 'SessionForkSource', + declaration: 'export type SessionForkSource = Session | SessionId;', + }, + { + name: 'SessionHeader', + declaration: 'export interface SessionHeader {\n version: number;\n id: SessionId;\n createdAt: number;\n cwd?: string;\n parentSession?: SessionId;\n seedLength?: number;\n}', + }, + { + name: 'SessionId', + declaration: 'export type SessionId = Branded<\'SessionId\'>;', + }, + { + name: 'StreamChunk', + declaration: 'export type StreamChunk = {\n type: \'block-start\';\n index: number;\n blockType: ContentBlockType;\n} | {\n type: \'text-delta\';\n index: number;\n text: string;\n} | {\n type: \'reasoning-delta\';\n index: number;\n text: string;\n} | {\n type: \'tool-call-delta\';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n} | {\n type: \'block-end\';\n index: number;\n block: ContentBlock;\n} | {\n type: \'usage\';\n usage: TokenUsage;\n} | {\n type: \'finish\';\n reason: FinishReason;\n};', + }, + { + name: 'StructuredOutputSchema', + declaration: 'export type StructuredOutputSchema = StructuredSchemaNode & {\n type: \'object\';\n};', + }, + { + name: 'StructuredScalar', + declaration: 'export type StructuredScalar = string | number | boolean | null;', + }, + { + name: 'StructuredSchemaNode', + declaration: 'export interface StructuredSchemaNode {\n type: StructuredSchemaType;\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: StructuredSchemaNode;\n enum?: StructuredScalar[];\n const?: StructuredScalar;\n description?: string;\n title?: string;\n default?: unknown;\n examples?: unknown;\n}', + }, + { + name: 'StructuredSchemaType', + declaration: 'export type StructuredSchemaType = \'object\' | \'array\' | \'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\';', + }, + { + name: 'SubagentCapabilities', + declaration: 'export interface SubagentCapabilities {\n outputSchema: boolean;\n depthLimit: boolean;\n toolFilter: boolean;\n}', + }, + { + name: 'SubagentProvider', + declaration: 'export interface SubagentProvider {\n readonly name: string;\n readonly capabilities: SubagentCapabilities;\n readonly inheritsParentContext: boolean;\n start(request: SubagentStartRequest): SubagentRun;\n}', + }, + { + name: 'SubagentResult', + declaration: 'export interface SubagentResult {\n output: ContentBlock[];\n structured?: unknown;\n stopReason: SubagentStopReason;\n}', + }, + { + name: 'SubagentRun', + declaration: 'export interface SubagentRun {\n readonly id: AgentId;\n readonly result: Promise;\n cancel(reason?: string): void;\n dispose(): Promise;\n sendMessage?(content: ContentBlock[]): void;\n resume?(content: ContentBlock[]): SubagentRun;\n}', + }, + { + name: 'SubagentStartRequest', + declaration: 'export interface SubagentStartRequest {\n prompt: ContentBlock[];\n parent: Agent;\n signal?: AbortSignal;\n agentOptions?: AgentOptions;\n outputSchema?: StructuredOutputSchema;\n maxDepth?: number;\n toolFilter?: {\n allow?: string[];\n deny?: string[];\n };\n}', + }, + { + name: 'SubagentStopReason', + declaration: 'export type SubagentStopReason = SubagentStopReasonMap[keyof SubagentStopReasonMap];', + }, + { + name: 'SubagentStopReasonMap', + declaration: 'export interface SubagentStopReasonMap {\n completed: \'completed\';\n aborted: \'aborted\';\n error: \'error\';\n \'max-tokens\': \'max-tokens\';\n refusal: \'refusal\';\n}', + }, + { + name: 'SurfaceEventType', + declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'context/message\' | \'steering/message\';', + }, + { + name: 'SurfaceOp', + declaration: 'export type SurfaceOp = \'append\' | {\n op: \'replace\';\n start: number;\n end: number;\n};', + }, + { + name: 'TerminalCallView', + declaration: 'export interface TerminalCallView {\n card: \'terminal\';\n title: string;\n description?: string;\n cwd?: string;\n}', + }, + { + name: 'TerminalResultView', + declaration: 'export interface TerminalResultView {\n card: \'terminal\';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n}', + }, + { + name: 'TodoItem', + declaration: 'export interface TodoItem {\n content: string;\n status: \'pending\' | \'in_progress\' | \'completed\';\n}', + }, + { + name: 'TokenUsage', + declaration: 'export interface TokenUsage {\n inputTokens: number;\n outputTokens: number;\n cacheReadTokens?: number;\n cacheWriteTokens?: number;\n reasoningTokens?: number;\n}', + }, + { + name: 'ToolCallBlock', + declaration: 'export interface ToolCallBlock {\n type: \'tool-call\';\n id: CallId;\n name: string;\n arguments: string;\n}', + }, + { + name: 'ToolCallKind', + declaration: 'export type ToolCallKind = \'read\' | \'edit\' | \'delete\' | \'move\' | \'search\' | \'execute\' | \'fetch\' | \'other\';', + }, + { + name: 'ToolCallView', + declaration: 'export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;', + }, + { + name: 'ToolDefinition', + declaration: 'export interface ToolDefinition extends ToolSchema {\n execute(args: unknown, exec: ToolExecution): Promise;\n timeoutMs?: number;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}', + }, + { + name: 'ToolErrorInfo', + declaration: 'export interface ToolErrorInfo {\n name: string;\n code: string;\n}', + }, + { + name: 'ToolExecuteReturn', + declaration: 'export type ToolExecuteReturn = ContentBlock[] | {\n content: ContentBlock[];\n meta?: unknown;\n};', + }, + { + name: 'ToolExecution', + declaration: 'export interface ToolExecution {\n callId: CallId;\n name: string;\n arguments: unknown;\n agent?: Agent;\n signal?: AbortSignal;\n}', + }, + { + name: 'ToolExecutionResult', + declaration: 'export interface ToolExecutionResult {\n callId: CallId;\n content: ContentBlock[];\n isError: boolean;\n error?: ToolErrorInfo;\n additionalContext?: HookContext;\n meta?: unknown;\n}', + }, + { + name: 'ToolResult', + declaration: 'export interface ToolResult {\n content: ContentBlock[];\n isError: boolean;\n meta?: unknown;\n}', + }, + { + name: 'ToolResultBlock', + declaration: 'export interface ToolResultBlock {\n type: \'tool-result\';\n toolCallId: CallId;\n content: ContentBlock[];\n isError?: boolean;\n}', + }, + { + name: 'ToolResultView', + declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;', + }, + { + name: 'ToolSchema', + declaration: 'export interface ToolSchema {\n name: string;\n description: string;\n parameters: Record;\n}', + }, + { + name: 'TurnEndReason', + declaration: 'export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];', + }, + { + name: 'TurnEndReasonMap', + declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n reason?: string;\n };\n error: {\n kind: \'error\';\n step: number;\n message: string;\n code?: string;\n };\n disposed: {\n kind: \'disposed\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n rejected: {\n kind: \'rejected\';\n reason: string;\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', + }, + { + name: 'TurnTrigger', + declaration: 'export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];', + }, + { + name: 'TurnTriggerMap', + declaration: 'export interface TurnTriggerMap {\n message: {\n kind: \'message\';\n source: MessageSource;\n };\n injection: {\n kind: \'injection\';\n source: MessageSource;\n };\n}', + }, + { + name: 'WebExecContext', + declaration: 'export interface WebExecContext {\n readonly signal?: AbortSignal;\n}', + }, + { + name: 'WebFetchBody', + declaration: 'export type WebFetchBody = {\n readonly kind: \'html\';\n readonly content: string;\n} | {\n readonly kind: \'text\';\n readonly content: string;\n};', + }, + { + name: 'WebFetchProvider', + declaration: 'export interface WebFetchProvider {\n readonly id: string;\n status(): WebProviderStatus;\n fetch(request: WebFetchRequest, exec?: WebExecContext): Promise;\n}', + }, + { + name: 'WebFetchRequest', + declaration: 'export interface WebFetchRequest {\n readonly url: string;\n readonly timeoutMs?: number;\n}', + }, + { + name: 'WebFetchResult', + declaration: 'export interface WebFetchResult {\n readonly providerId: string;\n readonly url: string;\n readonly statusCode: number;\n readonly body: WebFetchBody;\n readonly truncated: boolean;\n}', + }, + { + name: 'WebProviderStatus', + declaration: 'export type WebProviderStatus = {\n readonly available: true;\n} | {\n readonly available: false;\n readonly reason: \'missing-credential\' | \'misconfigured\';\n};', + }, + { + name: 'WebSearchProvider', + declaration: 'export interface WebSearchProvider {\n readonly id: string;\n status(): WebProviderStatus;\n search(request: WebSearchRequest, exec?: WebExecContext): Promise;\n}', + }, + { + name: 'WebSearchRequest', + declaration: 'export interface WebSearchRequest {\n readonly query: string;\n readonly maxResults?: number;\n}', + }, + { + name: 'WebSearchResult', + declaration: 'export interface WebSearchResult {\n readonly providerId: string;\n readonly query: string;\n readonly content?: string;\n readonly sources: readonly WebSearchSource[];\n readonly truncated: boolean;\n}', + }, + { + name: 'WebSearchSource', + declaration: 'export interface WebSearchSource {\n readonly url: string;\n readonly title?: string;\n readonly snippet?: string;\n readonly publishedAt?: string;\n}', + }, +] + +/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */ +export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [ + { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' }, + { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).' }, + { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.' }, + { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.' }, + { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.' }, + { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).' }, + { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.' }, + { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).' }, + { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).' }, + { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).' }, +] diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/cordis/tool-cordis/src/fiber-state.ts new file mode 100644 index 0000000000..e46700c387 --- /dev/null +++ b/packages/cordis/tool-cordis/src/fiber-state.ts @@ -0,0 +1,39 @@ +/** + * Runtime mirror of the cordis `FiberState` const enum plus human-readable + * labels, shared by the mount lifecycle (state reporting) and the inspect + * renderers (tree and mount-table labels). + * + * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for + * Node's type-stripping runner to import, so the members are mirrored here as + * values — each typed (via the type-only import) as the cordis enum member it + * mirrors, so enum-typed reads like `fiber.state` compare against them under a + * shared enum type. Source of truth: vendor/cordis/src/fiber.ts (pinned; drift + * only happens through a deliberate vendor sync). + * + * @module @deepseek-ai/dsh-tool-cordis/fiber-state + */ + +import type { FiberState as FiberStateEnum } from 'cordis' + +/** Value mirror of the cordis `FiberState` const enum (see the module doc for why a mirror exists). */ +export const FiberState = { + PENDING: 0 as FiberStateEnum.PENDING, + LOADING: 1 as FiberStateEnum.LOADING, + ACTIVE: 2 as FiberStateEnum.ACTIVE, + FAILED: 3 as FiberStateEnum.FAILED, + DISPOSED: 4 as FiberStateEnum.DISPOSED, + UNLOADING: 5 as FiberStateEnum.UNLOADING, +} as const + +/** The cordis `FiberState` enum type, re-exported so mirror consumers need one import. */ +export type FiberState = FiberStateEnum + +/** Human-readable label for each {@link FiberState}, keyed by member (inlining-safe — no reverse mapping). */ +export const STATE_LABELS: Record = { + [FiberState.PENDING]: 'pending', + [FiberState.LOADING]: 'loading', + [FiberState.ACTIVE]: 'active', + [FiberState.FAILED]: 'failed', + [FiberState.DISPOSED]: 'disposed', + [FiberState.UNLOADING]: 'unloading', +} diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts new file mode 100644 index 0000000000..09d804771f --- /dev/null +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -0,0 +1,199 @@ +/** + * The registration boundary between sandboxed mount code and the real runtime: + * SchemaSpec validation with teaching errors, the marker-guarded + * `harness.defineTool` / `harness.registerTool` pair, the guarded `ctx` proxy a + * mounted plugin receives, and the plugin-shape helpers the mount lifecycle + * narrows sandbox return values with. + * + * Two realm facts drive the design. Objects built inside the vm carry the vm + * realm's `Object.prototype`, and the session log's append-time plainness check + * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects + * foreign-realm data — so every dynamic tool's `execute` return is JSON + * round-tripped into the host realm before it reaches the registry. And a + * malformed tool schema must fail at REGISTRATION, not when a later request + * assembles it — so dynamic `ctx.tools.register` calls accept only definitions + * produced by the sandbox's `harness.defineTool`, which asserts the SchemaSpec + * DSL up front. + * + * @module @deepseek-ai/dsh-tool-cordis/guard + */ + +import type { Context, Plugin } from 'cordis' +import { defineTool } from '@deepseek-ai/dsh-tools' +import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools' + +const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool') +const SCHEMA_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']) + +type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true } +type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown } + +function isPlainRecord(value: unknown): value is Record { + return Object.prototype.toString.call(value) === '[object Object]' +} + +/** Assert a sandbox-provided `parameters` value is a SchemaSpec object, with a teaching error for the common JSON-Schema mistake. */ +function assertSchemaSpec(value: unknown): void { + if (!isPlainRecord(value)) { + throw new Error('harness.defineTool parameters must be a SchemaSpec object') + } + if (value.type === 'object' && isPlainRecord(value.properties)) { + throw new Error( + 'harness.defineTool parameters use the SchemaSpec DSL (NOT JSON Schema).\n' + + ' ✗ { type: \'object\', properties: { name: { type: \'string\' } }, required: [\'name\'] }\n' + + ' ✓ { name: { type: \'string\', required: true } }\n' + + 'Remove the outer { type: \'object\', properties, required } wrapper; ' + + 'each key IS a property directly on the parameters object.', + ) + } + for (const [key, prop] of Object.entries(value)) { + assertSchemaProp(prop, `parameters.${key}`) + } +} + +function assertSchemaProp(value: unknown, path: string): void { + if (!isPlainRecord(value)) { + throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`) + } + if (!SCHEMA_TYPES.has(value.type)) { + throw new Error(`harness.defineTool ${path} must declare a valid type`) + } + if (value.required !== undefined && value.required !== true) { + throw new Error(`harness.defineTool ${path}.required must be true when present`) + } + if (value.properties !== undefined) { + if (value.type !== 'object') { + throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`) + } + assertSchemaSpec(value.properties) + } + if (value.items !== undefined) { + if (value.type !== 'array') { + throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`) + } + assertSchemaProp(value.items, `${path}.items`) + } +} + +function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition { + Object.defineProperty(tool, DYNAMIC_TOOL, { value: true }) + return tool as DynamicToolDefinition +} + +function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition { + if (!isPlainRecord(tool) || (tool as DynamicToolMarker)[DYNAMIC_TOOL] !== true) { + throw new Error('dynamic tool registration must use a tool returned by harness.defineTool(...)') + } +} + +/** + * The `harness.defineTool` handed into the sandbox: the real DSL, with the + * tool's `execute` return normalized into the host realm via a JSON round-trip + * (see the module doc). The round-trip also projects the return onto exactly + * what the log would durably store, so a non-JSON-serializable return surfaces + * as that one call's error instead of poisoning the turn. + * @param options - the standard `defineTool` options, with `parameters` asserted against the SchemaSpec DSL before the DSL sees them. + * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts. + */ +export function sandboxDefineTool(options: Parameters[0]): ToolDefinition { + assertSchemaSpec((options as { parameters?: unknown }).parameters) + const tool = defineTool(options) + const execute = tool.execute.bind(tool) + return markDynamicTool({ + ...tool, + async execute(args, exec) { + return JSON.parse(JSON.stringify(await execute(args, exec))) as ToolExecuteReturn + }, + }) +} + +/** + * The `harness.registerTool` handed into the sandbox: registers a + * marker-verified dynamic tool on the given context's registry. + * @param ctx - the (guarded) context whose `tools` service receives the tool. + * @param tool - a definition produced by {@link sandboxDefineTool}; anything else is rejected. + * @returns the registry disposer for the registration. + */ +export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void { + assertDynamicTool(tool) + return ctx.tools.register(tool) +} + +function bindMethod(value: unknown, target: object): unknown { + if (typeof value !== 'function') return value + return (...args: unknown[]): unknown => Reflect.apply(value, target, args) as unknown +} + +function guardedContext(ctx: Context): Context { + const tools = new Proxy(ctx.tools, { + get(target, prop) { + if (prop === 'register') { + return (tool: unknown): () => void => sandboxRegisterTool(ctx, tool) + } + const value = Reflect.get(target, prop, target) as unknown + return bindMethod(value, target) + }, + }) + return new Proxy(ctx, { + get(target, prop) { + if (prop === 'tools') return tools + if (prop === 'get') { + return (service: string): unknown => service === 'tools' ? tools : target.get(service) + } + const value = Reflect.get(target, prop, target) as unknown + return bindMethod(value, target) + }, + }) +} + +/** + * Narrow an arbitrary sandbox return value to a mountable cordis plugin: a + * function, or an object with an `apply` function. (A bare function passes the + * first arm, so the object arm never sees `Function.prototype.apply`.) + * @param value - whatever the mount code returned. + * @returns whether the value is mountable via `ctx.plugin`. + */ +export function isPlugin(value: unknown): value is Plugin { + if (typeof value === 'function') return true + return typeof value === 'object' && value !== null + && typeof (value as { apply?: unknown }).apply === 'function' +} + +/** + * Wrap a plugin so its `apply` receives a guarded context (`tools.register` + * only accepts tools from `harness.defineTool`). Both function-form and + * object-form plugins go through the same guard; everything else on the + * context — `on`, `provide`, `inject` resolution — passes through with correct + * `this` binding, so cross-mount provide/inject works unmodified. + * @param plugin - the plugin the mount code returned. + * @returns an equivalent plugin whose `apply` sees the guarded context. + */ +export function guardedPlugin(plugin: Plugin): Plugin { + if (typeof plugin === 'function') { + const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown + return { + name: pluginName(plugin), + apply(ctx: Context, config?: unknown) { + return functionPlugin(guardedContext(ctx), config) + }, + } + } + const objectPlugin = plugin as { apply(ctx: Context, config?: unknown): unknown } + return { + ...plugin, + apply(ctx: Context, config?: unknown) { + return objectPlugin.apply(guardedContext(ctx), config) + }, + } +} + +/** + * Display name for a mounted plugin: its `name` property, else anonymous. + * @param plugin - the plugin the mount code returned. + * @returns the human-readable name used in mount results and inspect output. + */ +export function pluginName(plugin: Plugin): string { + const named = (plugin as { name?: unknown }).name + if (typeof named === 'string' && named.length > 0) return named + return '' +} diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts new file mode 100644 index 0000000000..d4492b4768 --- /dev/null +++ b/packages/cordis/tool-cordis/src/index.ts @@ -0,0 +1,228 @@ +/** + * The self-referential cordis toolset: three model-facing tools that let the + * agent inspect and MODIFY the live cordis runtime it is running inside. + * + * - `cordis_inspect` — read-only: provided services, the plugin fiber tree + * (rendered as an ASCII tree), registered tools, the dynamic mounts, and the + * catalog-backed `api` / `events` references. + * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the + * code returns a cordis plugin, which is mounted as a child of a dedicated + * `cordis-dynamic` group fiber and tracked under an id (`dyn-1`, `dyn-2`, …). + * - `cordis_unmount` — dispose one dynamic mount by id, awaiting quiescence. + * + * Everything the model's plugin registers (listeners via `ctx.on`, tools via + * `harness.registerTool`, services via `ctx.provide`) is an effect on the + * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans + * it all up through the ordinary cordis lifecycle. The group fiber exists + * exactly so the dynamic mounts form ONE subtree: visible as a unit in the + * inspect tree and disposed as a unit with this plugin. Design home: + * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. + * + * The vm sandbox guards against ACCIDENTAL global pollution only — it is not a + * security boundary. The `ctx` handed to the mounted plugin's `apply` is the + * real, fully privileged runtime handle; that is the point of the toolset, so + * a deployment loads this plugin as deliberately as it grants a bash tool. + * + * Plugin export shape: named exports, NO default. The cordis Loader's + * `unwrapExports` does `exports.default ?? exports`, so a stray default would + * collapse the module to the bare `apply` and drop `inject`, crashing at load + * (see docs/postmortem/0001). + * + * @module @deepseek-ai/dsh-tool-cordis + */ + +import type { Context, Fiber } from 'cordis' +import z from 'schemastery' +import { defineTool } from '@deepseek-ai/dsh-tools' +import { STATE_LABELS } from './fiber-state.ts' +import { isPlugin, pluginName } from './guard.ts' +import { describeApi, describeDynamic, describeEvents, describePluginTree, describeServices, describeTools } from './inspect.ts' +import { missingServices, mountDynamic } from './mount.ts' +import type { DynamicMount } from './mount.ts' +import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts' +import { createSandbox, evaluateMountCode } from './sandbox.ts' + +export const name = 'tool-cordis' +export const inject = ['tools'] + +/** Config for the tool-cordis plugin: the sandbox evaluation bound. */ +export interface Config { + /** + * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm + * before evaluation is aborted (default 5000). An async body escapes this + * bound — see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance. + */ + vmTimeoutMs?: number +} + +/** Schemastery validator for {@link Config}: `vmTimeoutMs` must be at least 1 (defaults to 5000). */ +export const Config: z = z.object({ + vmTimeoutMs: z.number().min(1).default(5000), +}) + +/** {@link Config} with every defaulted field present, as schemastery resolves it at load. */ +type ResolvedConfig = Required + +/** + * Mount the three cordis tools on `ctx.tools` and create the `cordis-dynamic` + * group fiber every dynamic mount hangs under. + * @param ctx - the plugin context (`tools` injected). + * @param config - the schemastery-resolved {@link Config}. + */ +export function apply(ctx: Context, config: Config): void { + const { vmTimeoutMs } = config as ResolvedConfig + // The one group fiber every dynamic mount hangs under. Mounted here (a child + // of this plugin's fiber) so disposing tool-cordis cascades over the whole + // dynamic subtree — the ordinary parent→child fiber lifecycle, nothing extra. + const group = ctx.plugin({ name: 'cordis-dynamic', apply: () => {} }) + + const mounts = new Map() + let nextId = 1 + + /** The dynamic-mount id for a fiber, when that fiber is a tracked mount. */ + function mountIdOf(fiber: Fiber): string | undefined { + for (const [id, mount] of mounts) { + if (mount.fiber === fiber) return id + } + return undefined + } + + ctx.tools.register(defineTool({ + name: 'cordis_inspect', + description: + 'Inspect the live cordis runtime that is running THIS agent. Read-only. ' + + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), ' + + '`plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — ' + + 'dynamic mounts appear under the `cordis-dynamic` group with their ids), ' + + '`tools` (the model-facing tools currently registered, i.e. what you can call), ' + + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), ' + + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), ' + + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). ' + + 'Omit `what` to get all six sections.', + parameters: { + what: { + type: 'string', + enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'], + description: 'Limit the report to one section. Omit for all sections.', + }, + }, + execute(args): Promise<{ type: 'text'; text: string }[]> { + const sections: [heading: string, body: () => string[]][] = [ + ['services', () => describeServices(ctx)], + ['plugins', () => describePluginTree(ctx, mountIdOf)], + ['tools', () => describeTools(ctx)], + ['dynamic', () => describeDynamic(ctx, mounts)], + ['api', () => describeApi(ctx)], + ['events', () => describeEvents()], + ] + const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading) + const text = selected + .map(([heading, body]) => `## ${heading}\n${body().join('\n')}`) + .join('\n\n') + return Promise.resolve([{ type: 'text', text }]) + }, + presentCall: presentInspectCall, + })) + + ctx.tools.register(defineTool({ + name: 'cordis_mount', + description: + 'Mount a NEW cordis plugin into the live runtime that is running THIS agent ' + + '(self-modification). `code` runs as the body of an async JavaScript function ' + + 'in an isolated sandbox and MUST `return` a plugin. Two forms: ' + + 'FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever ' + + 'services are on the parent context, and accessing a service without inject ' + + '(e.g. ctx.bash) throws; use it only when you need no injected services. ' + + 'OBJECT form `return { name?, inject: [\'bash\', \'llm\', …], apply(ctx) { … } }` ' + + '— declares dependencies, and cordis activates the plugin only after the ' + + 'services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. ' + + 'BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists ' + + 'method signatures AND the type shapes of their arguments/returns (do not guess a ' + + 'field\'s type; e.g. a bash run\'s stdout is an object, not a string). ' + + 'Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe ' + + 'events (see cordis_inspect what:"events"), or call ' + + '`harness.registerTool(ctx, harness.defineTool({ name, description, parameters: ' + + '{ text: { type: \'string\', required: true } }, async execute(args) { … } }))` ' + + 'to give yourself a new tool — it becomes callable on your NEXT step. A ' + + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return ' + + '[{ type: \'text\', text: someString }]` — never a bare string. ' + + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and ' + + 'another may declare `inject: [\'name\']` to consume it — the consumer stays pending ' + + 'until the provider exists and returns to pending when the provider is unmounted. ' + + 'Everything registered inside `apply` is cleaned up automatically on unmount. ' + + 'Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness ' + + 'terminal), `harness.defineTool`, `harness.registerTool`, ' + + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`; ' + + 'there is no `require`, `process`, `Buffer`, or network. ' + + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). ' + + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a ' + + 'trailing `next` callback which MUST be called — returning without `next()` ' + + 'VETOES the call; prefer plain notification events unless you intend to ' + + 'intercept. (2) Never await something that only resolves after the current ' + + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). ' + + '(3) The sandbox prevents accidental global pollution, not malice: `ctx` is ' + + 'the real, fully privileged runtime handle.', + parameters: { + code: { + type: 'string', + required: true, + description: 'Body of an async JS function; must `return` the plugin to mount.', + }, + }, + async execute(args) { + const id = `dyn-${nextId++}` + const sandbox = createSandbox(id) + const evaluated = await evaluateMountCode(sandbox, args.code, id, vmTimeoutMs) + if (!isPlugin(evaluated)) { + if (evaluated === undefined) { + throw new Error( + 'mount code returned `undefined` — did you forget `return`?\n' + + ' ✓ return (ctx) => { … }\n' + + ' ✓ return { name: \'…\', inject: […], apply(ctx) { … } }', + ) + } + throw new Error( + 'mount code must `return` a plugin: a function, or an object with an `apply(ctx)` method', + ) + } + const fiber = await mountDynamic(group, evaluated) + mounts.set(id, { fiber, pluginName: pluginName(evaluated) }) + // A settled fiber that is not ACTIVE is waiting on unsatisfied inject — + // legal cordis semantics (it activates when the service appears), so keep + // it mounted but tell the model what it is waiting for. + const missing = missingServices(ctx, fiber) + const state = STATE_LABELS[fiber.state] + const note = missing.length > 0 + ? ` — waiting for service(s): ${missing.join(', ')} (activates when provided)` + : '' + return [{ type: 'text', text: `mounted ${id} (plugin "${pluginName(evaluated)}", state: ${state}${note})` }] + }, + presentCall: presentMountCall, + })) + + ctx.tools.register(defineTool({ + name: 'cordis_unmount', + description: + 'Dispose a plugin previously mounted with cordis_mount, by id. All its ' + + 'registrations (event listeners, tools, services) are cleaned up through ' + + 'the cordis effect lifecycle. Returns only after disposal has fully ' + + 'completed (quiescence, not just a request to stop).', + parameters: { + id: { + type: 'string', + required: true, + description: 'The dynamic mount id returned by cordis_mount (e.g. "dyn-1").', + }, + }, + async execute(args) { + const mount = mounts.get(args.id) + if (!mount) { + throw new Error(`no dynamic plugin with id "${args.id}" (list mounts with cordis_inspect what:"dynamic")`) + } + await mount.fiber.dispose() + mounts.delete(args.id) + return [{ type: 'text', text: `unmounted ${args.id} (plugin "${mount.pluginName}")` }] + }, + presentCall: presentUnmountCall, + })) +} diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/cordis/tool-cordis/src/inspect.ts new file mode 100644 index 0000000000..dfcc9a0c6b --- /dev/null +++ b/packages/cordis/tool-cordis/src/inspect.ts @@ -0,0 +1,225 @@ +/** + * Read-only renderers over the live runtime for `cordis_inspect`: the service + * list, the plugin fiber tree (ASCII), the registered tools, the dynamic-mount + * table (with per-mount provides/waits), and the catalog-backed `api` / + * `events` sections. Every renderer is a pure function of the runtime handles + * it receives — no session state, no clock — so inspect output is exactly the + * runtime it describes. + * + * @module @deepseek-ai/dsh-tool-cordis/inspect + */ + +import type { Context, Fiber } from 'cordis' +import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts' +import type { EventApiEntry, InheritedApiEntry, ServiceApiEntry, TypeApiEntry } from './api-catalog.ts' +import { FiberState, STATE_LABELS } from './fiber-state.ts' +import { missingServices } from './mount.ts' +import type { DynamicMount } from './mount.ts' + +/** The live service registrations from `ctx.reflect.store` (map + filter keeps the possibly-undefined index read branch-free). */ +function liveImpls(ctx: Context): { name: string; fiber: Fiber }[] { + const store = ctx.reflect.store + return Object.getOwnPropertySymbols(store) + .map(key => store[key]) + .filter((impl): impl is NonNullable => impl !== undefined) +} + +/** Whether `fiber` is `root` itself or mounted anywhere inside `root`'s subtree. */ +function withinFiber(fiber: Fiber, root: Fiber): boolean { + let current = fiber + while (true) { + if (current === root) return true + const parent = current.parent.fiber + if (parent === current) return false + current = parent + } +} + +/** The service names provided by a mount's fiber subtree, sorted. */ +function providedBy(ctx: Context, fiber: Fiber): string[] { + return liveImpls(ctx) + .filter(impl => withinFiber(impl.fiber, fiber)) + .map(impl => impl.name) + .sort() +} + +/** + * The `services` section: every provided ctx service with its owning fiber, + * annotating non-active owners with their lifecycle state. + * @param ctx - the runtime to enumerate. + * @returns one line per service, or a single placeholder line when none are provided. + */ +export function describeServices(ctx: Context): string[] { + const lines = liveImpls(ctx).map((impl) => { + const active = impl.fiber.state === FiberState.ACTIVE + return `- ${impl.name} (provided by ${impl.fiber.name}${active ? '' : `, ${STATE_LABELS[impl.fiber.state]}`})` + }) + return lines.length > 0 ? lines : ['(no services provided)'] +} + +/** The tree node shape {@link renderTree} draws: one line per fiber, children indented. */ +interface TreeNode { + label: string + children: TreeNode[] +} + +/** Render a node list as an ASCII tree (`├─`/`└─` box drawing). */ +function renderTree(nodes: TreeNode[], prefix = ''): string[] { + return nodes.flatMap((node, index) => { + const last = index === nodes.length - 1 + const line = `${prefix}${last ? '└─' : '├─'} ${node.label}` + const childPrefix = `${prefix}${last ? ' ' : '│ '}` + return [line, ...renderTree(node.children, childPrefix)] + }) +} + +/** + * The `plugins` section: every fiber the registry knows, rebuilt into the + * parent→child tree from each fiber's mounting context and rendered as an + * ASCII tree with lifecycle states. Fibers whose parent fiber is outside the + * registry (i.e. mounted on the root context) become roots. + * @param ctx - the runtime whose registry is walked. + * @param mountIdOf - resolves a fiber to its dynamic-mount id, so mounts render as `dyn-: name`. + * @returns the tree lines, starting at the synthetic `root` line. + */ +export function describePluginTree(ctx: Context, mountIdOf: (fiber: Fiber) => string | undefined): string[] { + const fibers = new Set() + for (const runtime of ctx.registry.values()) { + for (const fiber of runtime.fibers) fibers.add(fiber) + } + const childrenOf = new Map() + const roots: Fiber[] = [] + for (const fiber of fibers) { + const parent = fiber.parent.fiber + if (fibers.has(parent)) { + const siblings = childrenOf.get(parent) ?? [] + siblings.push(fiber) + childrenOf.set(parent, siblings) + } else { + roots.push(fiber) + } + } + const byUid = (a: Fiber, b: Fiber): number => (a.uid ?? Infinity) - (b.uid ?? Infinity) + const toNode = (fiber: Fiber): TreeNode => { + const id = mountIdOf(fiber) + const label = `${id ? `${id}: ` : ''}${fiber.name} [${STATE_LABELS[fiber.state]}]` + const children = (childrenOf.get(fiber) ?? []).sort(byUid).map(toNode) + return { label, children } + } + return ['root', ...renderTree(roots.sort(byUid).map(toNode))] +} + +/** + * The `tools` section: the model-facing tool names currently registered. + * @param ctx - the runtime whose tool registry is read. + * @returns one line per registered tool. + */ +export function describeTools(ctx: Context): string[] { + return ctx.tools.schemas().map(schema => `- ${schema.name}`) +} + +/** + * The `dynamic` section: one line per mount with id, plugin name, lifecycle + * state, the services its subtree provides, and — for a pending mount — the + * services it waits for. + * @param ctx - the runtime the mounts live in. + * @param mounts - the tracked mounts, in mount order. + * @returns one line per mount, or a single placeholder line when none exist. + */ +export function describeDynamic(ctx: Context, mounts: ReadonlyMap): string[] { + if (mounts.size === 0) return ['(no dynamic plugins mounted)'] + return [...mounts].map(([id, mount]) => { + const provides = providedBy(ctx, mount.fiber) + const waiting = missingServices(ctx, mount.fiber) + const providesNote = provides.length > 0 ? ` — provides: ${provides.join(', ')}` : '' + const waitingNote = waiting.length > 0 ? ` — waiting for: ${waiting.join(', ')}` : '' + return `- ${id}: ${mount.pluginName} [${STATE_LABELS[mount.fiber.state]}]${providesNote}${waitingNote}` + }) +} + +/** + * The transitive closure of catalogued type shapes referenced (word-bounded) + * by the seed texts — the runtime scoping that keeps the `api` section to the + * shapes the LIVE signatures actually mention. + */ +function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEntry[] { + const included = new Map() + let frontier = seeds + while (frontier.length > 0) { + const next: string[] = [] + for (const entry of types) { + if (included.has(entry.name)) continue + const pattern = new RegExp(`\\b${entry.name}\\b`) + if (frontier.some(text => pattern.test(text))) { + included.set(entry.name, entry) + next.push(entry.declaration) + } + } + frontier = next + } + return [...included.values()].sort((a, b) => a.name.localeCompare(b.name)) +} + +/** + * The `api` section: the generated service catalog intersected with the LIVE + * runtime — catalogued live services render summary + method signatures, live + * services without a catalog entry (e.g. ones another mount provides) render + * name + owning fiber, catalog services that are not running are listed + * tersely, the type shapes the live signatures reference follow, and the + * inherited `ctx` surface closes the section. + * @param ctx - the runtime to intersect the catalog with. + * @param api - the service catalog (the generated one by default; injectable for tests). + * @param inherited - the inherited `ctx` surface lines (generated by default; injectable for tests). + * @param types - the type-shape catalog (generated by default; injectable for tests). + * @returns the section lines. + */ +export function describeApi( + ctx: Context, + api: readonly ServiceApiEntry[] = SERVICE_API, + inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API, + types: readonly TypeApiEntry[] = TYPE_API, +): string[] { + const live = new Map() + for (const impl of liveImpls(ctx)) live.set(impl.name, impl.fiber.name) + const lines: string[] = [] + const liveMethodTexts: string[] = [] + for (const entry of api) { + if (!live.has(entry.key)) continue + lines.push(`- ${entry.key} — ${entry.summary}`) + for (const method of entry.methods) { + lines.push(` ${method}`) + liveMethodTexts.push(method) + } + } + const catalogued = new Set(api.map(entry => entry.key)) + for (const [name, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) { + if (!catalogued.has(name)) lines.push(`- ${name} (provided by ${fiber}, no catalog entry)`) + } + const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key) + if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`) + const shapes = typeClosure(liveMethodTexts, types) + if (shapes.length > 0) { + lines.push('type shapes (referenced by the signatures above — read these before assuming a field is a string):') + for (const shape of shapes) { + for (const declLine of shape.declaration.split('\n')) lines.push(` ${declLine}`) + } + } + lines.push('inherited ctx API:') + for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`) + return lines +} + +/** + * The `events` section: every harness event with its dispatch mode, one-line + * summary, and exact signature, closed by the waterfall caution. + * @param events - the event catalog (the generated one by default; injectable for tests). + * @returns the section lines. + */ +export function describeEvents(events: readonly EventApiEntry[] = EVENT_API): string[] { + const lines = events.flatMap(event => [ + `- ${event.name} [${event.mode}] — ${event.summary}`, + ` ${event.signature}`, + ]) + lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.') + return lines +} diff --git a/packages/cordis/tool-cordis/src/mount.ts b/packages/cordis/tool-cordis/src/mount.ts new file mode 100644 index 0000000000..a222e81da1 --- /dev/null +++ b/packages/cordis/tool-cordis/src/mount.ts @@ -0,0 +1,64 @@ +/** + * Dynamic-mount lifecycle over the `cordis-dynamic` group fiber: settle a + * sandbox-produced plugin as a child fiber (never leaving a failed fiber + * mounted), and report the services a settled-but-pending fiber still waits + * for. Disposal needs no helper — a mount unwinds through an ordinary awaited + * `fiber.dispose()`, because everything the plugin registered is an effect on + * its fiber. + * + * @module @deepseek-ai/dsh-tool-cordis/mount + */ + +import type { Context, Fiber, Plugin } from 'cordis' +import { guardedPlugin } from './guard.ts' + +/** One tracked dynamic mount: the fiber plus the display name captured at mount time. */ +export interface DynamicMount { + /** The child fiber under the `cordis-dynamic` group. */ + fiber: Fiber + /** The plugin's display name at mount time (its `name`, else ``). */ + pluginName: string +} + +/** + * Mount a plugin under the group fiber and settle it. The group fiber loads + * asynchronously right after the owning plugin's `apply`, so it is awaited + * before hanging a child off its context. The child fiber's `await()` settles + * its lifecycle work and rethrows a startup error (e.g. a throwing `apply`); + * on error the fiber is disposed first — a failed mount never lingers. + * @param group - the `cordis-dynamic` group fiber every mount hangs under. + * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before mounting. + * @returns the settled child fiber (possibly pending on unsatisfied `inject`). + */ +export async function mountDynamic(group: Fiber, plugin: Plugin): Promise { + await group.await() + const fiber = group.ctx.plugin(guardedPlugin(plugin)) + try { + await fiber.await() + } catch (error) { + await fiber.dispose() + const message = error instanceof Error ? error.message : String(error) + // The commonest startup collision is remounting a NEW version of a tool + // while the old mount still holds the name — teach the replace recipe. + if (message.includes('already registered')) { + throw new Error( + `${message} — to REPLACE something an earlier mount registered, first cordis_unmount that mount's id ` + + '(find it with cordis_inspect what:"dynamic"), then mount the new version.', + ) + } + throw error instanceof Error ? error : new Error(message) + } + return fiber +} + +/** + * The services a fiber declared in `inject` that do not exist yet — a settled + * fiber that is not active is waiting on exactly these (legal cordis + * semantics: it activates when the service appears). + * @param ctx - the context to resolve service existence against. + * @param fiber - the mount fiber whose `inject` declarations are checked. + * @returns the missing service names, in declaration order. + */ +export function missingServices(ctx: Context, fiber: Fiber): string[] { + return Object.keys(fiber.inject).filter(service => ctx.get(service) === undefined) +} diff --git a/packages/cordis/tool-cordis/src/present.ts b/packages/cordis/tool-cordis/src/present.ts new file mode 100644 index 0000000000..614b070193 --- /dev/null +++ b/packages/cordis/tool-cordis/src/present.ts @@ -0,0 +1,51 @@ +/** + * ACP render intents for the three cordis tools — all `generic` cards, decided + * up front as part of the tool design. Presenters are pure functions of the + * call arguments (they run on replay too): no I/O, no session state, no clock. + * No `presentResult` overrides exist — the tools' text results are their + * correct completed rendering. + * + * @module @deepseek-ai/dsh-tool-cordis/present + */ + +import type { GenericCallView } from '@deepseek-ai/dsh-tools' + +/** + * The `cordis_inspect` call card: a read, titled with the requested section. + * @param args - the validated call arguments. + * @returns the generic card the ACP bridge renders. + */ +export function presentInspectCall(args: { what?: string }): GenericCallView { + return { + card: 'generic', + kind: 'read', + title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`, + } +} + +/** + * The `cordis_mount` call card: an execute carrying the mount code as raw input. + * @param args - the validated call arguments. + * @returns the generic card the ACP bridge renders. + */ +export function presentMountCall(args: { code: string }): GenericCallView { + return { + card: 'generic', + kind: 'execute', + title: 'Mount plugin into live cordis runtime', + rawInput: { code: args.code }, + } +} + +/** + * The `cordis_unmount` call card: a delete, titled with the mount id. + * @param args - the validated call arguments. + * @returns the generic card the ACP bridge renders. + */ +export function presentUnmountCall(args: { id: string }): GenericCallView { + return { + card: 'generic', + kind: 'delete', + title: `Unmount ${args.id}`, + } +} diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts new file mode 100644 index 0000000000..4d3eb16dfc --- /dev/null +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -0,0 +1,153 @@ +/** + * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose + * globals are a tagged write-through console, the `harness` registration + * helpers, and the encoding primitives a bare vm context lacks. The sandbox + * guards against ACCIDENTAL global pollution only — it is not a security + * boundary; the `ctx` a mounted plugin's `apply` later receives is the real, + * fully privileged runtime handle, and that is the point of the toolset. + * + * @module @deepseek-ai/dsh-tool-cordis/sandbox + */ + +import { createContext, runInContext } from 'node:vm' +import { sandboxDefineTool, sandboxRegisterTool } from './guard.ts' + +/** + * A write-through console for one sandbox, tagging every line with the mount + * id. Write-through (host stdout/stderr), NOT buffered into the tool result: + * a mounted listener fires long after the mount call returned, and its output + * must land somewhere the user can see — for the stdio demo, the terminal. + */ +function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | 'debug', (...args: unknown[]) => void> { + const tag = `[cordis:${id}]` + const log = (...args: unknown[]): void => { console.log(tag, ...args) } + const error = (...args: unknown[]): void => { console.error(tag, ...args) } + return { log, info: log, warn: log, debug: log, error } +} + +/** + * Per-sandbox prelude: give the vm realm's own constructors a + * `Symbol.hasInstance` that checks BOTH realms. Model code runs against a + * fresh vm realm, but most objects it touches are HOST-realm (the `args` a + * tool's `execute` receives, event payloads a listener observes, service + * return values), so a plain `x instanceof Array` / `instanceof Object` in + * sandbox code would silently be false. The patch replaces each vm + * constructor's own `[Symbol.hasInstance]` with "ordinary check against the + * vm constructor OR the host counterpart" — the ordinary algorithm is a pure + * prototype-chain walk, so calling it with the host constructor as receiver + * needs no host-side change. ONLY vm-realm globals are modified; host + * intrinsics are passed in as values and never touched. + */ +const DUAL_REALM_INSTANCEOF_PRELUDE = ` +(hostIntrinsics) => { + 'use strict' + const ordinary = Function.prototype[Symbol.hasInstance] + for (const name of Object.keys(hostIntrinsics)) { + const VmCtor = globalThis[name] + const HostCtor = hostIntrinsics[name] + if (typeof VmCtor !== 'function' || typeof HostCtor !== 'function') continue + Object.defineProperty(VmCtor, Symbol.hasInstance, { + value: (instance) => ordinary.call(VmCtor, instance) || ordinary.call(HostCtor, instance), + configurable: true, + }) + } +} +` + +/** Run {@link DUAL_REALM_INSTANCEOF_PRELUDE} in a freshly created sandbox, handing it the host intrinsics to pair up. */ +function patchDualRealmInstanceof(sandbox: object): void { + const patch = runInContext(DUAL_REALM_INSTANCEOF_PRELUDE, sandbox) as (intrinsics: Record) => void + patch({ Object, Array, Function, Error, TypeError, RangeError, SyntaxError, Promise, RegExp, Date, Map, Set }) +} + +/** + * Build the vm context one `cordis_mount` call evaluates in: the tagged + * console, the `harness` registration helpers, the encoding primitives, and + * the dual-realm `instanceof` patch, already `createContext`-ed. + * @param id - the mount id (`dyn-`), used as the console tag and filename stem. + * @returns the contextified sandbox object to pass to {@link evaluateMountCode}. + */ +export function createSandbox(id: string): object { + const sandbox = { + console: taggedConsole(id), + harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool }, + // Web APIs absent from fresh vm contexts — made available so the model + // can encode/decode base64 without Buffer (which is also absent). + btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'), + atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'), + TextEncoder, + TextDecoder, + } + createContext(sandbox) + patchDualRealmInstanceof(sandbox) + return sandbox +} + +/** + * Cross-realm SyntaxError detection: a compile failure inside `runInContext` + * constructs its error in the SANDBOX realm, so a host `instanceof + * SyntaxError` is silently false — the `name` property is the realm-safe tag. + */ +function isSyntaxError(error: unknown): error is Error { + return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'SyntaxError' +} + +/** + * The parse-failure context a vm `SyntaxError` carries: the vm prints the + * offending source line and a caret before the message, which is exactly what + * a model needs to self-correct — surface it instead of the bare message. + * Falls back to `String(error)` when the stack carries no such prelude. + * @param error - the `SyntaxError` (host- or sandbox-realm) thrown while compiling mount code. + * @returns the stack prefix up to and including the `SyntaxError: …` line. + */ +export function syntaxErrorContext(error: Error): string { + const lines = (error.stack ?? '').split('\n') + const messageIndex = lines.findIndex(line => line.startsWith('SyntaxError')) + if (messageIndex === -1) return String(error) + return lines.slice(0, messageIndex + 1).join('\n') +} + +/** + * Evaluate mount code as the body of an async function inside the sandbox. + * `vmTimeoutMs` only bounds the SYNCHRONOUS portion; an async body escapes it + * — acceptable under the module's trust stance. A parse failure is answered + * with the offending line + caret and a teaching hint: TypeScript syntax on + * the failing line gets the remove-annotations fix, anything else gets the + * function-body/bracket-balance reminder (models habitually close the returned + * plugin object with `});` as if it were a callback argument). + * @param sandbox - the contextified object from {@link createSandbox}. + * @param code - the model-written function body; must `return` a plugin. + * @param id - the mount id, used as the vm filename (`cordis-mount-.js`). + * @param vmTimeoutMs - the synchronous evaluation bound in milliseconds. + * @returns whatever the code returned, still un-narrowed (the mount lifecycle checks plugin shape). + */ +export async function evaluateMountCode(sandbox: object, code: string, id: string, vmTimeoutMs: number): Promise { + try { + return await runInContext( + `(async () => {\n${code}\n})()`, + sandbox, + { filename: `cordis-mount-${id}.js`, timeout: vmTimeoutMs }, + ) + } catch (error) { + if (!isSyntaxError(error)) throw error + const context = syntaxErrorContext(error) + // Scope the TypeScript heuristic to the OFFENDING line, not the whole + // code: an ` as ` inside an ordinary description string must not turn a + // plain syntax error into a misleading remove-annotations message. + const offendingLine = context.split('\n')[1] ?? '' + if (/\bas\b/.test(offendingLine)) { + throw new Error( + `mount code failed to parse:\n${context}\n` + + 'The sandbox runs plain JavaScript, not TypeScript. Remove type annotations:\n' + + ' ✗ { type: \'text\' as const, text: x }\n' + + ' ✓ { type: \'text\', text: x }', + ) + } + throw new Error( + `mount code failed to parse:\n${context}\n` + + 'Note: `code` runs as the BODY of an async function (line numbers are offset by the 1-line wrapper). ' + + 'Check bracket balance — ending the returned plugin object with `});` closes a call that was never opened; ' + + 'a plain `return { … }` ends with `}` (an optional `;`), never `)`.', + ) + } +} diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts new file mode 100644 index 0000000000..f68eaef639 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts @@ -0,0 +1,105 @@ +import { describe, expect, it } from 'vitest' +import { call, CONSUMER_CODE, PROVIDER_CODE, setup, text } from './helpers.ts' + +/** + * Cross-mount composition through ordinary cordis provide/inject semantics: + * one mount provides a service, another injects it, and mount ids stay the + * lifecycle handles. Every assertion is against the WORLD — the registry, the + * service store, real tool dispatch — not the tool's own summary line. + */ + +describe('cross-mount provide/inject', () => { + it('provider first: the consumer activates immediately and its tool reaches the provided service', async () => { + const ctx = await setup() + const provider = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + expect(text(provider)).toContain('state: active') + + const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) + expect(consumer.isError).toBe(false) + expect(text(consumer)).toContain('state: active') + + // The vm-realm service value is callable across mounts, and the result + // normalizes into the host realm like any dynamic tool result. + const greeted = await call(ctx, 'greet', { name: 'harness' }) + expect(greeted.isError).toBe(false) + expect(text(greeted)).toBe('hi harness') + }) + + it('consumer first: stays pending naming the missing service, then activates when the provider mounts', async () => { + const ctx = await setup() + const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) + expect(consumer.isError).toBe(false) + expect(text(consumer)).toContain('state: pending') + expect(text(consumer)).toContain('waiting for service(s): greeter') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('waiting for: greeter') + expect(ctx.tools.get('greet')).toBeUndefined() + + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + expect(ctx.tools.get('greet')).toBeDefined() + expect(text(await call(ctx, 'greet', { name: 'late' }))).toBe('hi late') + }) + + it('unmounting the provider sends the consumer back to pending and unwinds its registrations', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) // dyn-2 + expect(ctx.tools.get('greet')).toBeDefined() + + const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(unmounted.isError).toBe(false) + expect(ctx.tools.get('greet')).toBeUndefined() + const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' })) + expect(report).toContain('dyn-2: greeter-consumer [pending] — waiting for: greeter') + }) + + it('re-providing the service re-runs the consumer through the same guard (active again, tool back)', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) // dyn-2 + await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(ctx.tools.get('greet')).toBeUndefined() + + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-3 + expect(ctx.tools.get('greet')).toBeDefined() + expect(text(await call(ctx, 'greet', { name: 'again' }))).toBe('hi again') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-2: greeter-consumer [active]') + }) + + it('a duplicate provide fails loud with the owning fiber named, and the failed mount is disposed', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + const duplicate = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + expect(duplicate.isError).toBe(true) + expect(text(duplicate)).toContain('has been registered') + const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' })) + expect(report).toContain('dyn-1: greeter-provider') + expect(report).not.toContain('dyn-2') + }) + + it('inspect surfaces the linkage: provides on the provider row, the service in services and api sections', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) + + const dynamic = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' })) + expect(dynamic).toContain('dyn-1: greeter-provider [active] — provides: greeter') + + const services = text(await call(ctx, 'cordis_inspect', { what: 'services' })) + expect(services).toContain('- greeter (provided by greeter-provider)') + + const api = text(await call(ctx, 'cordis_inspect', { what: 'api' })) + expect(api).toContain('- greeter (provided by greeter-provider, no catalog entry)') + }) + + it('unmounting the consumer leaves the provider and its service intact', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) // dyn-2 + await call(ctx, 'cordis_unmount', { id: 'dyn-2' }) + + expect(ctx.tools.get('greet')).toBeUndefined() + const services = text(await call(ctx, 'cordis_inspect', { what: 'services' })) + expect(services).toContain('- greeter (provided by greeter-provider)') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-1: greeter-provider [active]') + }) +}) diff --git a/packages/cordis/tool-cordis/tests/helpers.ts b/packages/cordis/tool-cordis/tests/helpers.ts new file mode 100644 index 0000000000..b183a2444f --- /dev/null +++ b/packages/cordis/tool-cordis/tests/helpers.ts @@ -0,0 +1,104 @@ +import { Context } from 'cordis' +import Timer from '@cordisjs/plugin-timer' +import { CallId } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import type { ToolDefinition, ToolExecutionResult } from '@deepseek-ai/dsh-tools' +import * as tool from '../src/index.ts' + +/** + * Shared spec helpers: a real `SystemPrompt` + `ToolRegistry` + timer + + * tool-cordis tree (only the model is absent — the code strings below stand in + * for what it would write), plus the canonical mount-code fixtures the suites + * share. + */ + +/** Mount the plugin on a fresh context with a real ToolRegistry and the timer service. */ +export async function setup(config?: tool.Config): Promise { + const ctx = new Context() + await ctx.plugin(Timer) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(tool, config) + return ctx +} + +let callCounter = 0 + +/** Execute a registered tool through the real registry pipeline. */ +export function call(ctx: Context, name: string, args: unknown): Promise { + return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args }) +} + +/** Concatenated text blocks of one tool result. */ +export function text(result: ToolExecutionResult): string { + return result.content.filter(block => block.type === 'text').map(block => block.text).join('') +} + +/** Mount code for a listener plugin: logs on every `tools/change`. */ +export const LISTENER_CODE = ` + return { + name: 'change-logger', + apply(ctx) { + ctx.on('tools/change', () => console.log('tools changed')) + }, + } +` + +/** Mount code for a self-made tool: registers `reverse_text` via the sandbox's harness helpers. */ +export const REVERSE_TOOL_CODE = ` + return { + name: 'reverse-text', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'reverse_text', + description: 'Reverse a string.', + parameters: { text: { type: 'string', required: true } }, + async execute(args) { + return [{ type: 'text', text: args.text.split('').reverse().join('') }] + }, + })) + }, + } +` + +/** Mount code providing a `greeter` service other mounts can inject. */ +export const PROVIDER_CODE = ` + return { + name: 'greeter-provider', + apply(ctx) { + ctx.provide('greeter', { greet: (name) => 'hi ' + name }) + }, + } +` + +/** Mount code consuming the `greeter` service through inject, exposing it as a tool. */ +export const CONSUMER_CODE = ` + return { + name: 'greeter-consumer', + inject: ['greeter', 'tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'greet', + description: 'Greet someone via the greeter service.', + parameters: { name: { type: 'string', required: true } }, + async execute(args) { + return [{ type: 'text', text: ctx.greeter.greet(args.name) }] + }, + })) + }, + } +` + +/** A registrable no-op tool the tests use to trigger a real `tools/change`. */ +export function dummyTool(name: string): ToolDefinition { + return { + name, + description: 'test trigger', + parameters: { type: 'object' as const, properties: {} }, + async execute(): Promise<[]> { + return [] + }, + } +} diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/cordis/tool-cordis/tests/inspect.spec.ts new file mode 100644 index 0000000000..c45d3b29a8 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/inspect.spec.ts @@ -0,0 +1,123 @@ +import { describe, expect, it } from 'vitest' +import type { Context, Fiber } from 'cordis' +import { FiberState } from '../src/fiber-state.ts' +import { describeApi, describeEvents, describePluginTree, describeServices } from '../src/inspect.ts' +import { call, LISTENER_CODE, setup, text } from './helpers.ts' + +/** + * The `cordis_inspect` sections: rendered against the real runtime through the + * tool, plus direct renderer calls for the states a minimal harness cannot + * reach (empty service store, uid-less fibers, a fully-live catalog). + */ + +describe('cordis_inspect', () => { + it('reports all six sections by default', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_inspect', {}) + expect(result.isError).toBe(false) + const report = text(result) + for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) { + expect(report).toContain(`## ${heading}`) + } + // The services section sees the real providers; the tree shows the dynamic + // group under this plugin; the tools section lists the cordis tools. + expect(report).toContain('- tools (provided by ToolRegistry)') + expect(report).toMatch(/tool-cordis \[active\]/) + expect(report).toMatch(/cordis-dynamic \[active\]/) + expect(report).toContain('- cordis_mount') + expect(report).toContain('(no dynamic plugins mounted)') + }) + + it('limits the report to one section via `what`', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_inspect', { what: 'tools' }) + const report = text(result) + expect(report).toContain('## tools') + expect(report).not.toContain('## services') + expect(report).not.toContain('## plugins') + }) + + it('shows a mount in the dynamic section and as an annotated child of the group in the tree', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + const report = text(await call(ctx, 'cordis_inspect', {})) + expect(report).toContain('- dyn-1: change-logger [active]') + expect(report).toMatch(/dyn-1: change-logger \[active\]/) + }) + + it('renders the api section from the generated catalog intersected with the LIVE runtime', async () => { + const ctx = await setup() + const report = text(await call(ctx, 'cordis_inspect', { what: 'api' })) + // Live catalogued services render summary + signatures. + expect(report).toContain('- tools — ') + expect(report).toContain('register(definition: ToolDefinition)') + expect(report).toContain('- systemPrompt — ') + // Catalogued services with no live provider are listed tersely. + expect(report).toMatch(/not running \(loadable services with no live provider\): .*bash/) + // The type shapes the LIVE signatures reference follow (closure over the + // generated TYPE_API — a consumer can see field types, not just names). + expect(report).toContain('type shapes (referenced by the signatures above') + expect(report).toContain('export interface ToolExecution') + // A type only reachable through a NOT-live service (e.g. bash) is scoped out. + expect(report).not.toContain('export interface BashRunResult') + // The inherited ctx surface closes the section. + expect(report).toContain('inherited ctx API:') + expect(report).toContain('- ctx.effect — ') + }) + + it('renders the events section with mode badges, signatures, and the waterfall caution', async () => { + const ctx = await setup() + const report = text(await call(ctx, 'cordis_inspect', { what: 'events' })) + expect(report).toContain('- tools/change [emit]') + expect(report).toContain('- tools/pre-execute [waterfall]') + expect(report).toMatch(/'agent\/status'\(/) + expect(report).toContain('returning without next() vetoes the chain') + }) +}) + +describe('inspect renderers (direct)', () => { + it('describeServices reports an empty store as such, and labels a non-active provider', () => { + const empty = { reflect: { store: {} } } as unknown as Context + expect(describeServices(empty)).toEqual(['(no services provided)']) + + const pendingFiber = { state: FiberState.PENDING, name: 'half-loaded' } as unknown as Fiber + const store: Record = {} + store[Symbol('impl')] = { name: 'thing', fiber: pendingFiber } + const ctx = { reflect: { store } } as unknown as Context + expect(describeServices(ctx)).toEqual(['- thing (provided by half-loaded, pending)']) + }) + + it('describePluginTree sorts uid-less fibers last and renders sibling branches', () => { + // The parent fiber is OUTSIDE the registry set, so all three are roots. + const rootFiber = { uid: 0, name: 'root' } as unknown as Fiber + const fiber = (uid: number | null, name: string): Fiber => + ({ uid, name, state: FiberState.ACTIVE, parent: { fiber: rootFiber } }) as unknown as Fiber + const a = fiber(2, 'beta') + const b = fiber(1, 'alpha') + const c = fiber(null, 'rootless') + const d = fiber(null, 'rootless-too') + const ctx = { registry: { values: () => [{ fibers: [a, b, c, d] }] } } as unknown as Context + expect(describePluginTree(ctx, () => undefined)).toEqual([ + 'root', + '├─ alpha [active]', + '├─ beta [active]', + '├─ rootless [active]', + '└─ rootless-too [active]', + ]) + }) + + it('describeApi omits the not-running line and type shapes when nothing applies', async () => { + const ctx = await setup() + const lines = describeApi(ctx, [{ key: 'tools', summary: 'The registry.', methods: ['register(x): void'] }], [], []) + expect(lines[0]).toBe('- tools — The registry.') + expect(lines[1]).toBe(' register(x): void') + expect(lines.join('\n')).not.toContain('not running') + expect(lines.join('\n')).not.toContain('type shapes') + }) + + it('describeEvents renders an empty catalog as just the waterfall caution', () => { + expect(describeEvents([])).toEqual([ + 'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.', + ]) + }) +}) diff --git a/packages/cordis/tool-cordis/tests/integration.spec.ts b/packages/cordis/tool-cordis/tests/integration.spec.ts new file mode 100644 index 0000000000..94331df7c0 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/integration.spec.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import * as ToolCordis from '../src/index.ts' +import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +import { REVERSE_TOOL_CODE } from './helpers.ts' + +/** + * Full-loop integration: a scripted mock model mounts a plugin that registers + * a NEW tool, calls that tool on the very next step (tool schemas are + * reassembled per step — the real loop proves the self-extension contract), + * and unmounts it again. Only the model is mocked; the sandbox, the fiber + * tree, and the session log are real. + */ + +async function harness(adapter: MockAdapter): Promise { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(ToolCordis) + 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() + } + }) + }) +} + +describe('cordis tools through the agent loop', () => { + it('mounts a tool, calls it on the next step, and unmounts it — all as real tool/call events', async () => { + const adapter = new MockAdapter([ + toolCallResponse('call-1', 'cordis_mount', { code: REVERSE_TOOL_CODE }, 'Extending myself.'), + toolCallResponse('call-2', 'reverse_text', { text: 'harness' }), + toolCallResponse('call-3', 'cordis_unmount', { id: 'dyn-1' }), + textResponse('Done.'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('it-cordis'), { model: 'mock' }) + + agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }]) + await waitForIdle(ctx, agent) + + const log = agent.session.events + const calls = log.filter(event => event.type === 'tool/call').map(event => event.data.name) + expect(calls).toEqual(['cordis_mount', 'reverse_text', 'cordis_unmount']) + + const results = log.filter(event => event.type === 'tool/result') + expect(results.map(event => event.data.isError)).toEqual([false, false, false]) + const reversed = results[1]!.data.content + .filter(block => block.type === 'text') + .map(block => block.text) + .join('') + expect(reversed).toBe('ssenrah') + + // After the unmount the self-made tool is gone from the registry. + expect(ctx.tools.get('reverse_text')).toBeUndefined() + }) +}) diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts new file mode 100644 index 0000000000..5bdde09b53 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -0,0 +1,409 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { isJsonValue } from '@deepseek-ai/dsh-session' +import { syntaxErrorContext } from '../src/sandbox.ts' +import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts' + +/** + * The `cordis_mount` success/failure family: real plugins land on a genuine + * cordis fiber tree, their registrations are observable through the real + * registry/event bus, and every rejection path teaches the fix. + */ + +afterEach(() => { + vi.restoreAllMocks() +}) + +describe('cordis_mount', () => { + it('mounts a listener plugin that observes real events, tagged-logging through to the host console', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + + const result = await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('mounted dyn-1 (plugin "change-logger", state: active)') + + // Fire a REAL tools/change by registering a tool; the mounted listener logs. + ctx.tools.register(dummyTool('trigger_a')) + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tools changed') + }) + + it('mounts a bare-function plugin as , and a named function under its name', async () => { + const ctx = await setup() + const anonymous = await call(ctx, 'cordis_mount', { code: 'return (ctx) => { ctx.on(\'tools/change\', () => {}) }' }) + expect(anonymous.isError).toBe(false) + expect(text(anonymous)).toContain('plugin ""') + const named = await call(ctx, 'cordis_mount', { code: 'return function watcher(ctx) {}' }) + expect(text(named)).toContain('plugin "watcher"') + }) + + it('lets the agent give ITSELF a new tool, immediately callable through the registry', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + expect(result.isError).toBe(false) + + expect(ctx.tools.schemas().map(schema => schema.name)).toContain('reverse_text') + const reversed = await call(ctx, 'reverse_text', { text: 'harness' }) + expect(reversed.isError).toBe(false) + expect(text(reversed)).toBe('ssenrah') + }) + + it('normalizes a self-made tool\'s result into the host realm, so the session log accepts it', async () => { + // The model's execute builds its content blocks INSIDE the vm, where + // Object.prototype is a different object — dsh-session's isJsonValue (the + // gate every `tool/result` append runs through) compares prototype + // IDENTITY, so a raw foreign-realm result would error the whole turn the + // first time the self-made tool runs. harness.defineTool round-trips the + // return into host-realm JSON before it reaches the registry. + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + const reversed = await call(ctx, 'reverse_text', { text: 'harness' }) + expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true) + }) + + it('rejects JSON Schema passed to harness.defineTool with the SchemaSpec teaching error', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'bad-json-schema-tool', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'bad_json_schema_tool', + description: 'bad', + parameters: { + type: 'object', + properties: { text: { type: 'string' } }, + required: ['text'], + }, + async execute() { return [{ type: 'text', text: 'bad' }] }, + })) + }, + } + `, + }) + + expect(result.isError).toBe(true) + expect(text(result)).toContain('harness.defineTool parameters use the SchemaSpec DSL') + expect(ctx.tools.get('bad_json_schema_tool')).toBeUndefined() + }) + + it.each([ + ['parameters: 42', 'must be a SchemaSpec object'], + ['parameters: { text: 42 }', 'parameters.text must be a SchemaSpec property object'], + ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type'], + ['parameters: { text: { type: \'string\', required: false } }', 'parameters.text.required must be true when present'], + ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is only valid for type "object"'], + ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is only valid for type "array"'], + ])('rejects a malformed SchemaSpec (%s) with a teaching error', async (parameters, message) => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'bad-schema', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'bad_schema_tool', + description: 'bad', + ${parameters}, + async execute() { return [] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain(message) + }) + + it('accepts a nested object/array SchemaSpec (the DSL recursion)', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'nested-schema', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'nested_schema_tool', + description: 'nested', + parameters: { + item: { type: 'object', required: true, properties: { label: { type: 'string', required: true } } }, + tags: { type: 'array', items: { type: 'string' } }, + }, + async execute(args) { return [{ type: 'text', text: args.item.label }] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(false) + const echoed = await call(ctx, 'nested_schema_tool', { item: { label: 'ok' }, tags: ['a'] }) + expect(text(echoed)).toBe('ok') + }) + + it('rejects raw dynamic ctx.tools.register calls that bypass harness helpers', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'raw-register', + inject: ['tools'], + apply(ctx) { + ctx.tools.register({ + name: 'raw_dynamic_tool', + description: 'raw', + parameters: { type: 'object', properties: {} }, + async execute() { return [] }, + }) + }, + } + `, + }) + + expect(result.isError).toBe(true) + expect(text(result)).toContain('dynamic tool registration must use a tool returned by harness.defineTool') + expect(ctx.tools.get('raw_dynamic_tool')).toBeUndefined() + }) + + it('guards the registry reached through ctx.get(\'tools\') identically', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'raw-register-get', + apply(ctx) { + const sp = ctx.get('systemPrompt') + console.log('systemPrompt is', typeof sp) + ctx.get('tools').register({ name: 'raw_via_get', description: 'raw', parameters: {}, async execute() { return [] } }) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('dynamic tool registration must use a tool returned by harness.defineTool') + expect(ctx.tools.get('raw_via_get')).toBeUndefined() + }) + + it('passes non-register registry members through the guard with correct binding', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'schema-reader', + inject: ['tools'], + apply(ctx) { + console.log('sees', ctx.tools.schemas().length, 'tools; mount is', typeof ctx.tools.get('cordis_mount')) + }, + } + `, + }) + expect(result.isError).toBe(false) + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'sees', 3, 'tools; mount is', 'object') + }) + + it('keeps a plugin with unsatisfied inject mounted as pending and names what it waits for', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'waiter\', inject: [\'no-such-service\'], apply(ctx) {} }', + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('state: pending') + expect(text(result)).toContain('waiting for service(s): no-such-service') + // Unmounting a pending mount works like any other. + const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(unmounted.isError).toBe(false) + }) + + it('rejects code that throws, leaving nothing mounted', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'throw new Error(\'boom in sandbox\')' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('boom in sandbox') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('passes non-Error and null throws through untouched (no SyntaxError misclassification)', async () => { + const ctx = await setup() + const primitive = await call(ctx, 'cordis_mount', { code: 'throw \'plain-string-throw\'' }) + expect(primitive.isError).toBe(true) + expect(text(primitive)).toContain('plain-string-throw') + const nullish = await call(ctx, 'cordis_mount', { code: 'throw null' }) + expect(nullish.isError).toBe(true) + }) + + it('rejects code that does not return a plugin', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'return 42' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('must `return` a plugin') + }) + + it('answers a missing return with the two valid plugin forms', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'const plugin = (ctx) => {}' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('did you forget `return`?') + }) + + it('disposes a plugin whose apply throws, and reports the error', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'broken\', apply(ctx) { throw new Error(\'apply exploded\') } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('apply exploded') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('rolls back a plugin that collides with an existing tool name, keeping the original tool intact', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'usurper', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'cordis_mount', + description: 'dup', + parameters: {}, + async execute() { return [] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('already registered') + expect(text(result)).toContain('first cordis_unmount') + // The original cordis_mount still dispatches — the failed fiber is gone. + const retry = await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + expect(retry.isError).toBe(false) + }) + + it('isolates sandbox globals: no process/require, and globalThis writes do not leak to the host', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + globalThis.__cordis_tool_leak = 'leaked' + return { name: 'probe-' + typeof process + '-' + typeof require, apply(ctx) {} } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('plugin "probe-undefined-undefined"') + expect((globalThis as Record).__cordis_tool_leak).toBeUndefined() + }) + + it('provides btoa/atob and the tagged console variants inside the sandbox', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const error = vi.spyOn(console, 'error').mockImplementation(() => {}) + const result = await call(ctx, 'cordis_mount', { + code: ` + console.warn('warned') + console.error('errored') + const round = atob(btoa('hi')) + const bytes = new TextEncoder().encode(round) + return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.fiber) } } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('plugin "codec-hi"') + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'warned') + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'object') + expect(error).toHaveBeenCalledWith('[cordis:dyn-1]', 'errored') + }) + + it('answers TypeScript syntax in the plain-JS sandbox with the fix', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'ts\' as const, apply(ctx) {} }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('plain JavaScript, not TypeScript') + }) + + it('surfaces the offending line + caret and the bracket-balance hint on a syntax error', async () => { + const ctx = await setup() + // The canonical model mistake: closing the returned object with `});` as + // if it were a callback argument. The word "as" in a STRING elsewhere must + // not trigger the TypeScript hint — the heuristic reads the failing line. + const result = await call(ctx, 'cordis_mount', { + code: 'const note = \'treat pattern as regex\'\nreturn {\n name: \'oops\',\n apply(ctx) {}\n});', + }) + expect(result.isError).toBe(true) + const message = text(result) + expect(message).toContain('failed to parse') + expect(message).toContain('});') + expect(message).toContain('^') + expect(message).toContain('BODY of an async function') + expect(message).not.toContain('TypeScript') + }) + + it('syntaxErrorContext falls back to String(error) when the stack has no vm prelude', () => { + const doctored = new SyntaxError('boom') + delete (doctored as { stack?: string }).stack + expect(syntaxErrorContext(doctored)).toBe('SyntaxError: boom') + const plain = new SyntaxError('bang') + plain.stack = 'not-a-vm-stack' + expect(syntaxErrorContext(plain)).toBe('SyntaxError: bang') + }) + + it('handles a runtime-thrown SyntaxError (no source-line prelude) with the generic hint', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'throw new SyntaxError(\'user-crafted\')' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('failed to parse') + expect(text(result)).toContain('user-crafted') + }) + + it('honors the configured vmTimeoutMs for the synchronous portion', async () => { + const ctx = await setup({ vmTimeoutMs: 50 }) + const result = await call(ctx, 'cordis_mount', { code: 'while (true) {}' }) + expect(result.isError).toBe(true) + expect(text(result)).toMatch(/timed? ?out/i) + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('makes instanceof inside the sandbox see BOTH realms (patched vm constructors, host untouched)', async () => { + // The args a tool's execute receives are HOST-realm objects; without the + // dual-realm Symbol.hasInstance prelude, `args.items instanceof Array` in + // sandbox code is silently false. The patch lives on the vm realm's own + // constructors only — the host realm's must stay pristine. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'probe-instanceof', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'probe_instanceof', + description: 'report instanceof checks across realms', + parameters: { items: { type: 'array', required: true, items: { type: 'string' } } }, + async execute(args) { + const checks = { + hostArray: args.items instanceof Array, + hostObject: args instanceof Object, + vmArray: [] instanceof Array, + vmObject: ({}) instanceof Object, + } + return [{ type: 'text', text: JSON.stringify(checks) }] + }, + })) + }, + } + `, + }) + const probed = await call(ctx, 'probe_instanceof', { items: ['a'] }) + expect(probed.isError).toBe(false) + expect(JSON.parse(text(probed))).toEqual({ hostArray: true, hostObject: true, vmArray: true, vmObject: true }) + // The host realm's constructors keep their default instanceof: no own + // Symbol.hasInstance was added to them. + expect(Object.getOwnPropertySymbols(Object)).not.toContain(Symbol.hasInstance) + expect(Object.getOwnPropertySymbols(Array)).not.toContain(Symbol.hasInstance) + }) +}) diff --git a/packages/cordis/tool-cordis/tests/present.spec.ts b/packages/cordis/tool-cordis/tests/present.spec.ts new file mode 100644 index 0000000000..d8f380439f --- /dev/null +++ b/packages/cordis/tool-cordis/tests/present.spec.ts @@ -0,0 +1,41 @@ +import { describe, expect, it } from 'vitest' +import { presentInspectCall, presentMountCall, presentUnmountCall } from '../src/present.ts' +import { setup } from './helpers.ts' + +/** + * Render-intent presenters: pure functions of the call args (no I/O, no + * session state — they run on replay too), wired onto the registered tools. + */ + +describe('presenters', () => { + it('cordis_inspect renders a generic read card titled with the section', () => { + expect(presentInspectCall({})).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime' }) + expect(presentInspectCall({ what: 'api' })).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime: api' }) + }) + + it('cordis_mount renders a generic execute card carrying the code as raw input', () => { + expect(presentMountCall({ code: 'return (ctx) => {}' })).toEqual({ + card: 'generic', + kind: 'execute', + title: 'Mount plugin into live cordis runtime', + rawInput: { code: 'return (ctx) => {}' }, + }) + }) + + it('cordis_unmount renders a generic delete card titled with the id', () => { + expect(presentUnmountCall({ id: 'dyn-1' })).toEqual({ card: 'generic', kind: 'delete', title: 'Unmount dyn-1' }) + }) + + it('is wired onto the registered definitions through the defineTool soft-validation path', async () => { + const ctx = await setup() + expect(ctx.tools.get('cordis_inspect')!.presentCall!({ what: 'tools' })).toEqual({ + card: 'generic', + kind: 'read', + title: 'Inspect cordis runtime: tools', + }) + expect(ctx.tools.get('cordis_mount')!.presentCall!({ code: 'return 1' })).toMatchObject({ kind: 'execute' }) + expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount dyn-2' }) + // Soft validation: presenter args that fail the schema render as no card, never a throw. + expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 42 })).toBeUndefined() + }) +}) diff --git a/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts b/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts new file mode 100644 index 0000000000..8953b5da94 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts @@ -0,0 +1,49 @@ +import { describe, expect, it } from 'vitest' +import Loader from '@cordisjs/plugin-loader' +import * as tool from '../src/index.ts' +import { setup } from './helpers.ts' + +/** + * Export-shape and registration surface: the namespace-plugin contract the + * real Loader path depends on, the registered tool set, and the Config + * validator's defaults and rejections. + */ + +describe('export shape', () => { + it('has no default export, and survives the real Loader unwrapExports', () => { + // A stray `export default` would make `unwrapExports` (`exports.default ?? + // exports`) collapse the module to the bare function and DROP `inject`, + // crashing at real load (docs/postmortem/0001). Assert directly AND through + // the real unwrap so adding `export default apply` fails here. + expect('default' in tool).toBe(false) + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(tool) as Record + expect(unwrapped).toBe(tool) + expect(unwrapped.name).toBe('tool-cordis') + expect(unwrapped.inject).toEqual(['tools']) + expect(typeof unwrapped.apply).toBe('function') + expect(typeof unwrapped.Config).toBe('function') + }) +}) + +describe('tool registration', () => { + it('registers the three cordis tools with the documented schemas', async () => { + const ctx = await setup() + const names = ctx.tools.schemas().map(schema => schema.name) + expect(names).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount'])) + const inspect = ctx.tools.schemas().find(schema => schema.name === 'cordis_inspect')! + const props = (inspect.parameters as { properties: Record }).properties + expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) + }) +}) + +describe('Config', () => { + it('defaults vmTimeoutMs to 5000', () => { + expect(new tool.Config()).toEqual({ vmTimeoutMs: 5000 }) + }) + + it('rejects a non-positive vmTimeoutMs at validation time (misconfiguration fails loud)', () => { + expect(() => new tool.Config({ vmTimeoutMs: 0 })).toThrow() + expect(() => new tool.Config({ vmTimeoutMs: -1 })).toThrow() + }) +}) diff --git a/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts b/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts new file mode 100644 index 0000000000..718a213968 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts @@ -0,0 +1,82 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import * as tool from '../src/index.ts' +import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts' + +/** + * Disposal semantics: `cordis_unmount` reaches quiescence before returning, + * and disposing the tool-cordis fiber itself (the HMR path) cascades over the + * whole dynamic subtree through the ordinary parent→child fiber lifecycle. + */ + +afterEach(() => { + vi.restoreAllMocks() +}) + +describe('cordis_unmount', () => { + it('disposes the mount and its registrations have stopped by the time it returns (quiescence)', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + + ctx.tools.register(dummyTool('trigger_before')) + expect(log).toHaveBeenCalledTimes(1) + + const result = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('unmounted dyn-1') + + // Immediately after the awaited unmount, the listener must be gone — no + // grace period, no eventual consistency. + ctx.tools.register(dummyTool('trigger_after')) + expect(log).toHaveBeenCalledTimes(1) + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('unregisters a self-made tool on unmount', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + expect(ctx.tools.get('reverse_text')).toBeDefined() + + await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(ctx.tools.get('reverse_text')).toBeUndefined() + }) + + it('rejects an unknown id, and a second unmount of the same id', async () => { + const ctx = await setup() + const unknown = await call(ctx, 'cordis_unmount', { id: 'dyn-99' }) + expect(unknown.isError).toBe(true) + expect(text(unknown)).toContain('no dynamic plugin with id "dyn-99"') + + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + const again = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(again.isError).toBe(true) + }) +}) + +describe('HMR safety', () => { + it('disposing the tool-cordis fiber cascades over the dynamic subtree and its registrations', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const fiber = await ctx.plugin(tool) + + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + expect(ctx.tools.get('reverse_text')).toBeDefined() + + await fiber.dispose() + + // The whole subtree is gone: the self-made tool, the cordis tools, and the + // mounted listener (no log on a fresh tools/change). + expect(ctx.tools.get('reverse_text')).toBeUndefined() + expect(ctx.tools.get('cordis_mount')).toBeUndefined() + const calls = log.mock.calls.length + ctx.tools.register(dummyTool('trigger_post_dispose')) + expect(log).toHaveBeenCalledTimes(calls) + }) +}) diff --git a/packages/cordis/tool-cordis/tsconfig.json b/packages/cordis/tool-cordis/tsconfig.json new file mode 100644 index 0000000000..c4d4b6f656 --- /dev/null +++ b/packages/cordis/tool-cordis/tsconfig.json @@ -0,0 +1,27 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/timer" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../core/tools" + } + ] +} diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index cacc2eef66..d4a6b97243 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { it('boots every shipped tool package and harvests its model-facing schemas', async () => { const catalog = await collectToolCatalog() const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort() - expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) + expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) // Every tool carries a JSON-Schema `parameters` object (what the model sees). for (const entry of catalog) { for (const schema of entry.schemas) { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b538e82908..ab1b0f73b3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -191,6 +191,40 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/cordis/tool-cordis: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@cordisjs/plugin-loader': + specifier: ^1.0.0-rc.4 + version: 1.0.0-rc.4(cordis@4.0.0-rc.6) + '@cordisjs/plugin-timer': + specifier: workspace:^ + version: link:../../../vendor/timer + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-agent-loop': + specifier: workspace:^ + version: link:../../core/agent-loop + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/core/agent: devDependencies: '@deepseek-ai/dsh-brand': diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 24739e1388..714b15afdc 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -47,6 +47,7 @@ import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local' import SubagentService from '@deepseek-ai/dsh-subagent' import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' +import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis' import * as ToolFs from '@deepseek-ai/dsh-tool-fs' import * as ToolTodo from '@deepseek-ai/dsh-tool-todo' import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent' @@ -113,6 +114,18 @@ const TOOL_PACKAGES: ToolPackage[] = [ note: 'The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.', }, + { + pkg: '@deepseek-ai/dsh-tool-cordis', + dir: 'tool-cordis', + source: 'packages/cordis/tool-cordis/src/index.ts', + requires: ['ctx.tools'], + writes: ['tool/call', 'tool/result', 'live plugin-tree mutations (mount/unmount)'], + async mount(ctx) { + await ctx.plugin(ToolCordis) + }, + note: + 'Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes.', + }, { pkg: '@deepseek-ai/dsh-tool-fs', dir: 'tool-fs', diff --git a/tsconfig.base.json b/tsconfig.base.json index e587d44a3d..b4a4e116d8 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -51,6 +51,7 @@ "./packages/web/*/src", "./packages/timeout/*/src", "./packages/todo/*/src", + "./packages/cordis/*/src", "./packages/hooks/*/src", "./packages/session-persistence/*/src", "./packages/ui/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index 64fa70e9f9..fafe46d3c9 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -58,6 +58,7 @@ { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/guard/repeat-tool-guard" }, + { "path": "./packages/cordis/tool-cordis" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" } diff --git a/tsconfig.json b/tsconfig.json index 8feeea4fce..9d630d04c4 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -69,6 +69,7 @@ { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/guard/repeat-tool-guard" }, + { "path": "./packages/cordis/tool-cordis" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" } From 5edc9c573a6fd26d773cfcfcb933f0d138aa26c7 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:47:15 +0800 Subject: [PATCH 081/119] =?UTF-8?q?examples:=20cordis-agent=20=E2=80=94=20?= =?UTF-8?q?the=20self-referential=20demo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The coding spine (DeepSeek V4 + local bash on dsh-stdio-agent) plus @deepseek-ai/dsh-tool-cordis loaded by package name, run via demo:cordis. Ships the keyless Loader smoke (the export-shape / package-name-resolution guard) and the with-key smoke: a real model mounts a listener whose tagged console line actually fires, builds and calls its own reverse_text tool, and composes two mounts via provide/inject — all world-verified against the registry and session events. --- examples/cordis-agent/README.md | 33 ++++ examples/cordis-agent/cordis.yml | 64 +++++++ examples/cordis-agent/package.json | 7 + .../cordis-agent/tests/cordis-tools.e2e.ts | 156 ++++++++++++++++++ examples/cordis-agent/tests/harness.ts | 46 ++++++ .../cordis-agent/tests/keyless-smoke.e2e.ts | 94 +++++++++++ package.json | 1 + 7 files changed, 401 insertions(+) create mode 100644 examples/cordis-agent/README.md create mode 100644 examples/cordis-agent/cordis.yml create mode 100644 examples/cordis-agent/package.json create mode 100644 examples/cordis-agent/tests/cordis-tools.e2e.ts create mode 100644 examples/cordis-agent/tests/harness.ts create mode 100644 examples/cordis-agent/tests/keyless-smoke.e2e.ts diff --git a/examples/cordis-agent/README.md b/examples/cordis-agent/README.md new file mode 100644 index 0000000000..ba9365498b --- /dev/null +++ b/examples/cordis-agent/README.md @@ -0,0 +1,33 @@ +# cordis-agent + +The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). + +## Run it + +```sh +# repo root .env (gitignored) or exported env: +# DEEPSEEK_API_KEY=sk-… +# DEEPSEEK_BASE_URL=https://… # optional; defaults to the public API +pnpm run demo:cordis +``` + +The intended demo is staged — verify the listener link first, then let the agent extend itself: + +``` +> Mount a plugin that listens to the 'agent/status' event and logs every status change, then run `echo hi` with bash. + [tool call] cordis_mount({"code": "return { name: 'status-logger', apply(ctx) { ctx.on('agent/status', (agent, status) => console.log('status →', status)) } }"}) + [tool result] mounted dyn-1 (plugin "status-logger", state: active) + [tool call] bash({"command": "echo hi"}) +[cordis:dyn-1] status → … ← the mounted listener firing, live +> Now give yourself a reverse_text tool and use it on "harness". + [tool call] cordis_mount({"code": "return { name: 'reverse-text', inject: ['tools'], apply(ctx) { ctx.tools.register(harness.defineTool({ name: 'reverse_text', … })) } }"}) + [tool call] reverse_text({"text": "harness"}) ← a tool the agent built for itself, one step earlier +> Unmount both. + [tool call] cordis_unmount({"id": "dyn-1"}) +``` + +Ask for `cordis_inspect` with `what: "api"` or `what: "events"` to see the generated service/event reference the agent writes plugin code against, and try two cooperating mounts (`ctx.provide` in one, `inject` in the other) to watch cordis park and revive the consumer. + +## End-to-end tests + +`tests/keyless-smoke.e2e.ts` boots the real `cordis.yml` through the Loader with a dummy key and asserts the banner + clean EOF exit (the export-shape / real-load-path guard, now across the package-name resolution). `tests/cordis-tools.e2e.ts` is the with-key smoke: a real model mounts a status listener (asserting the tagged console line actually fires — the world, not the agent's claim), builds itself a `reverse_text` tool and uses it, and composes two mounts via provide/inject. The tool logic itself is unit-tested in [`packages/cordis/tool-cordis`](../../packages/cordis/tool-cordis) under the per-file 100% coverage gate. diff --git a/examples/cordis-agent/cordis.yml b/examples/cordis-agent/cordis.yml new file mode 100644 index 0000000000..b5e08c8325 --- /dev/null +++ b/examples/cordis-agent/cordis.yml @@ -0,0 +1,64 @@ +# The cordis-agent plugin tree: the SELF-REFERENTIAL harness demo. Same spine +# as coding-agent (DeepSeek V4 + local bash on @deepseek-ai/dsh-stdio-agent), +# plus @deepseek-ai/dsh-tool-cordis, which gives the model three tools over the +# live cordis runtime it is running inside: cordis_inspect (services / plugin +# tree / tools / dynamic mounts / api / events), cordis_mount (evaluate +# model-written code in a vm sandbox and mount the returned plugin under the +# `cordis-dynamic` group), and cordis_unmount (dispose one mount by id). +# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) — the +# dsh-stdio-agent bin loads the gitignored repo-root .env first. +# +# Trust stance (docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md): +# the mounted code gets the REAL ctx — the +# vm sandbox only prevents accidental global pollution. Load the toolset as +# deliberately as you would grant a bash tool. + +# Hot-module reload for the dev/demo loop (needs `node --expose-internals`). +- id: hmr + name: '@cordisjs/plugin-hmr' + config: + root: ['.'] + +# The DeepSeek adapter. +- id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + config: + apiKey: !!js process.env.DEEPSEEK_API_KEY + baseURL: !!js process.env.DEEPSEEK_BASE_URL + models: + - deepseek-v4-pro + - deepseek-v4-flash + +# Local bash executor for agent-core's tool-bash schema — gives the agent an +# ordinary tool whose calls make the mounted listeners observably fire. +- id: bash + name: '@deepseek-ai/dsh-bash-local' + config: + timeoutMs: 60000 + +# The stdio chat app: the whole spine + front-door cluster, configured for the +# self-referential demo driving a pre-created `main` agent. +- id: stdio-agent + name: '@deepseek-ai/dsh-stdio-agent' + config: + model: deepseek-v4-flash + resumeSessionId: !!js process.env.RESUME_SESSION_ID + persistenceRoot: './.sessions' + welcome: 'cordis-agent ready. Ask it to inspect its runtime, mount a listener, or invent a tool for itself.' + persona: | + You are cordis-agent, a self-referential harness demo powered by the + {{model}} model. + + You run INSIDE a cordis plugin runtime, and your cordis_* tools operate + on that live runtime: cordis_inspect to look around (its `api` and + `events` sections document the service methods, type shapes, and events + your plugin code can use), cordis_mount to add a plugin (an event + listener, a brand-new tool for yourself, or a service other mounts + inject), cordis_unmount to clean one up. Prefer small single-purpose + plugins, prefer plain notification events over waterfall events unless + you intend to intercept, and unmount what you no longer need. Report + results briefly. + +# The self-referential cordis toolset (loaded after the app so ctx.tools exists). +- id: tool-cordis + name: '@deepseek-ai/dsh-tool-cordis' diff --git a/examples/cordis-agent/package.json b/examples/cordis-agent/package.json new file mode 100644 index 0000000000..8d5a693555 --- /dev/null +++ b/examples/cordis-agent/package.json @@ -0,0 +1,7 @@ +{ + "name": "cordis-agent-example", + "private": true, + "version": "0.0.1", + "type": "module", + "description": "Runnable demo: the self-referential harness — an agent that inspects and modifies its own cordis runtime" +} diff --git a/examples/cordis-agent/tests/cordis-tools.e2e.ts b/examples/cordis-agent/tests/cordis-tools.e2e.ts new file mode 100644 index 0000000000..388fcb0058 --- /dev/null +++ b/examples/cordis-agent/tests/cordis-tools.e2e.ts @@ -0,0 +1,156 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import type { Context } from 'cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import { AgentId } from '@deepseek-ai/dsh-agent' +import { cordisHarness, waitForIdle } from './harness.ts' + +/** + * With-key smoke for the self-referential cordis tools: a REAL model drives + * cordis_mount/cordis_unmount against the live context the test observes. + * World-verified, not self-reported: the mounted listener must actually WRITE + * its tagged console line, the self-made tool must actually EXIST in the + * registry and appear as a real `tool/call`, the cross-mount service must + * actually LAND in the reflect store. Key-gated (see vitest.e2e.config.ts). + */ + +let ctx: Context | undefined + +afterEach(async () => { + vi.restoreAllMocks() + // Always dispose the harness, even on failure/retry/timeout: agent-loop + // teardown stops the loop, and disposing the tree unwinds every dynamic + // mount the model left behind. + await ctx?.fiber.dispose() + ctx = undefined +}) + +/** The tagged write-through lines (`[cordis:dyn-n] …`) captured by a console spy. */ +function taggedCalls(log: { mock: { calls: unknown[][] } }): unknown[][] { + return log.mock.calls.filter(call => typeof call[0] === 'string' && /^\[cordis:dyn-\d+\]$/.test(call[0])) +} + +/** Model-facing text of one tool result, concatenated. */ +function resultText(result: { content: { type: string; text?: string }[] }): string { + return result.content.filter(block => block.type === 'text').map(block => block.text).join('') +} + +describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modifies its own runtime', () => { + it('mounts a status listener whose tagged output actually fires, then unmounts it', async () => { + ctx = await cordisHarness() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const agent = ctx.agentLoop.create(AgentId('cordis-e2e-listener'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Use cordis_mount to mount a plugin that listens to the \'agent/status\' ' + + 'cordis event and logs every change with console.log. Reply "mounted" once done.', + }]) + await waitForIdle(ctx, agent) + + // The WORLD check: the turn's own running→idle transition must have driven + // the mounted listener through the tagged sandbox console. + expect(taggedCalls(log).length).toBeGreaterThan(0) + const mid = await ctx.tools.execute({ + callId: CallId('verify-mounted'), name: 'cordis_inspect', arguments: { what: 'dynamic' }, + }) + expect(resultText(mid)).toContain('dyn-') + + agent.send([{ type: 'text', text: 'Now unmount the plugin you just mounted.' }]) + await waitForIdle(ctx, agent) + + const after = await ctx.tools.execute({ + callId: CallId('verify-unmounted'), name: 'cordis_inspect', arguments: { what: 'dynamic' }, + }) + expect(resultText(after)).toContain('(no dynamic plugins mounted)') + }, 120_000) + + it('builds itself a reverse_text tool and actually calls it', async () => { + ctx = await cordisHarness() + const agent = ctx.agentLoop.create(AgentId('cordis-e2e-selftool'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Give yourself a new tool: use cordis_mount to mount a plugin with ' + + 'inject ["tools"] that calls harness.registerTool(ctx, harness.defineTool({...})) ' + + 'to register a tool named reverse_text with one required string parameter ' + + '"text", returning the text reversed. Then CALL reverse_text with the ' + + 'exact text "harness" and report its exact output.', + }]) + await waitForIdle(ctx, agent) + + // World checks: the tool exists in the registry, was invoked as a real + // tool call, and its RESULT (the self-made execute actually running) is the + // reversed string. The model's prose is not asserted — the tool result is + // the world; the summary sentence is just the self-report. + expect(ctx.tools.get('reverse_text')).toBeDefined() + const events = [...agent.session.events] + const calls = events.filter(event => event.type === 'tool/call') + expect(calls.some(event => event.data.name === 'cordis_mount')).toBe(true) + const reverseCalls = calls.filter(event => event.data.name === 'reverse_text') + expect(reverseCalls.length).toBeGreaterThan(0) + const reverseResults = events + .filter(event => event.type === 'tool/result') + .filter(event => reverseCalls.some(call => call.data.callId === event.data.callId)) + .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text)) + // On failure, surface what the model actually mounted and what the tool + // returned — an e2e failing at a distance is undebuggable without it. + const mountCode = calls + .filter(event => event.data.name === 'cordis_mount') + .map(event => event.data.arguments) + .join('\n---\n') + const trace = events.map((event) => { + switch (event.type) { + case 'tool/call': return `tool/call:${event.data.name}` + case 'tool/result': return `tool/result:${event.data.isError ? 'ERR:' + JSON.stringify(event.data.content).slice(0, 200) : 'ok'}` + case 'turn/end': return `turn/end:${JSON.stringify(event.data.reason)}` + default: return event.type + } + }).join('\n') + expect( + reverseResults.some(text => text.includes('ssenrah')), + `no reversed output in reverse_text results.\nresults: ${JSON.stringify(reverseResults)}\nmount code: ${mountCode}\ntrace:\n${trace}`, + ).toBe(true) + }, 120_000) + + it('composes two mounts through provide/inject, and unmounting the provider parks the consumer', async () => { + ctx = await cordisHarness() + const agent = ctx.agentLoop.create(AgentId('cordis-e2e-compose'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Mount TWO separate plugins with cordis_mount. First a provider: apply calls ' + + 'ctx.provide(\'shouter\', { shout: (s) => s.toUpperCase() }). Second a consumer with ' + + 'inject ["shouter", "tools"] that registers (via harness.registerTool + harness.defineTool) ' + + 'a tool named shout_text with one required string parameter "text" whose execute returns ' + + 'ctx.shouter.shout(args.text) as a text content block. Then CALL shout_text with "quiet" ' + + 'and report the exact output.', + }]) + await waitForIdle(ctx, agent) + + // World checks: the service is really in the store, the tool really ran. + expect(ctx.get('shouter')).toBeDefined() + expect(ctx.tools.get('shout_text')).toBeDefined() + const events = [...agent.session.events] + const shoutCalls = events + .filter(event => event.type === 'tool/call') + .filter(event => event.data.name === 'shout_text') + expect(shoutCalls.length).toBeGreaterThan(0) + const shoutResults = events + .filter(event => event.type === 'tool/result') + .filter(event => shoutCalls.some(call => call.data.callId === event.data.callId)) + .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text)) + expect(shoutResults.some(text => text.includes('QUIET'))).toBe(true) + + agent.send([{ type: 'text', text: 'Now unmount ONLY the provider plugin (the one that provided shouter).' }]) + await waitForIdle(ctx, agent) + + // The consumer must have been parked by cordis itself: service gone, + // dependent tool unregistered, dynamic table naming the missing service. + expect(ctx.get('shouter')).toBeUndefined() + expect(ctx.tools.get('shout_text')).toBeUndefined() + const after = await ctx.tools.execute({ + callId: CallId('verify-parked'), name: 'cordis_inspect', arguments: { what: 'dynamic' }, + }) + expect(resultText(after)).toContain('waiting for: shouter') + }, 120_000) +}) diff --git a/examples/cordis-agent/tests/harness.ts b/examples/cordis-agent/tests/harness.ts new file mode 100644 index 0000000000..78e5b0bb93 --- /dev/null +++ b/examples/cordis-agent/tests/harness.ts @@ -0,0 +1,46 @@ +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore 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 * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' +import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis' + +/** + * Shared harness for the cordis-agent e2e suite: the agent spine with the real + * DeepSeek adapter and the real `@deepseek-ai/dsh-tool-cordis` plugin, so a + * live model can mount plugins into the very context the test observes. Lives + * outside the *.e2e.ts pattern so importing it never re-registers another + * file's tests. + */ + +const PERSONA = 'You are cordis-agent, a self-referential harness demo. ' + + 'Your cordis_* tools operate on the live cordis runtime you run inside: ' + + 'cordis_inspect to look around, cordis_mount to add a plugin, cordis_unmount ' + + 'to clean one up. Follow the tool descriptions exactly and report results briefly.' + +export async function cordisHarness(): Promise { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: PERSONA }) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] }) + await ctx.plugin(ToolCordis) + return ctx +} + +export 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() + } + }) + }) +} diff --git a/examples/cordis-agent/tests/keyless-smoke.e2e.ts b/examples/cordis-agent/tests/keyless-smoke.e2e.ts new file mode 100644 index 0000000000..b37ea8d83e --- /dev/null +++ b/examples/cordis-agent/tests/keyless-smoke.e2e.ts @@ -0,0 +1,94 @@ +import { spawn, type ChildProcessWithoutNullStreams } 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' +import { afterEach, describe, expect, it } from 'vitest' + +/** + * Keyless Loader-path smoke for examples/cordis-agent: boot the REAL example + * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` — + * the cordis Loader, `unwrapExports`, the full plugin tree INCLUDING the + * `@deepseek-ai/dsh-tool-cordis` package resolved by name (whose `inject` + * would crash a collapsed export shape at load, see docs/postmortem/0001) — + * then close stdin with no prompt and assert the ready banner + a clean exit. + * + * No prompt is ever sent, so the model is NEVER called — that is why it runs + * without a real key: `llm-deepseek`'s apply() only requires a key to be + * PRESENT, and the absence of any prompt guarantees no network call. The + * with-key product proof lives in cordis-tools.e2e.ts. + */ + +// The dsh-stdio-agent bin (the demo:cordis entry) and this example's cordis.yml. +// The bin resolves its config-path arg from CWD; the test spawns from a temp +// cwd, so we pass the example config's ABSOLUTE path. +const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url)) +const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig +// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside +// the repo, so point it at the repo tsconfig (root is three levels up). +const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) + +let child: ChildProcessWithoutNullStreams | undefined +let workdir: string | undefined + +afterEach(async () => { + if (child !== undefined && child.exitCode === null) child.kill('SIGKILL') + child = undefined + if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) + workdir = undefined +}) + +async function bootAndEof(): Promise<{ stdout: string; code: number }> { + workdir = await mkdtemp(join(tmpdir(), 'cordis-smoke-')) + const cwd = workdir + return new Promise((resolve, reject) => { + const proc = spawn( + process.execPath, + // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:cordis). + ['--expose-internals', '--import', tsxLoader, binScript, configPath], + { + cwd, + env: { + ...process.env, + TSX_TSCONFIG_PATH: repoTsconfig, + // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots. + // No prompt is sent, so the adapter never streams — no network call. + DEEPSEEK_API_KEY: 'keyless-smoke-no-call', + }, + stdio: ['pipe', 'pipe', 'pipe'], + }, + ) + child = proc + let stdout = '' + let stderr = '' + proc.stdout.setEncoding('utf8') + proc.stdout.on('data', (chunk: string) => { stdout += chunk }) + proc.stderr.setEncoding('utf8') + proc.stderr.on('data', (chunk: string) => { stderr += chunk }) + + const timer = setTimeout(() => { + proc.kill('SIGKILL') + reject(new Error(`cordis-agent did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`)) + }, 10_000) + + proc.on('exit', (code) => { + clearTimeout(timer) + if (code === 0) resolve({ stdout, code }) + else reject(new Error(`cordis-agent exited ${code}. stderr:\n${stderr}`)) + }) + proc.on('error', (err) => { clearTimeout(timer); reject(err) }) + + // No prompt — just EOF, so the stdio UI exits without ever running a turn. + proc.stdin.end() + }) +} + +describe('cordis-agent keyless smoke (real cordis.yml via the Loader)', () => { + it('boots the full plugin tree incl. tool-cordis, prints its banner, and exits cleanly on EOF', async () => { + const { stdout, code } = await bootAndEof() + expect(code).toBe(0) + expect(stdout).toContain('cordis-agent ready.') + }, 15_000) +}) diff --git a/package.json b/package.json index bba471ea5f..e4b071718a 100644 --- a/package.json +++ b/package.json @@ -63,6 +63,7 @@ "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", + "demo:cordis": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/cordis-agent/cordis.yml", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, From 809329ea1ab6486fcc0774d39748eb8d6941adec Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:47:51 +0800 Subject: [PATCH 082/119] =?UTF-8?q?scripts:=20gen-cordis-api=20=E2=80=94?= =?UTF-8?q?=20the=20generated=20runtime=20API=20catalog=20pipeline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Emits packages/cordis/tool-cordis/src/api-catalog.ts (the data cordis_inspect serves the model) from the same JSDoc-enforcing AST walk as docs/cordis-catalog (collectServices/collectEvents, plus the now-exported INHERITED_SERVICES table): service summaries + method signatures, event modes + signatures, and the transitive closure of type shapes the signatures reference — so a mounted plugin reads that a bash run's stdout is { text, truncated } instead of guessing. verify-cordis-api joins doc-sync as the freshness gate. --- package.json | 4 +- scripts/gen-cordis-api.ts | 247 ++++++++++++++++++++++++++++++++++ scripts/gen-cordis-catalog.ts | 2 +- 3 files changed, 251 insertions(+), 2 deletions(-) create mode 100644 scripts/gen-cordis-api.ts diff --git a/package.json b/package.json index e4b071718a..652a8d88c4 100644 --- a/package.json +++ b/package.json @@ -47,6 +47,8 @@ "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts", "gen-rfc-index": "tsx scripts/gen-rfc-index.ts", "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check", + "gen-cordis-api": "tsx scripts/gen-cordis-api.ts", + "verify-cordis-api": "tsx scripts/gen-cordis-api.ts --check", "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts", "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts", "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check", @@ -59,7 +61,7 @@ "gen-module-graph": "tsx scripts/gen-module-graph.ts", "verify-module-graph": "tsx scripts/gen-module-graph.ts --check", "constraints": "tsx scripts/check-workspace-constraints.ts", - "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets", + "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets", "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", diff --git a/scripts/gen-cordis-api.ts b/scripts/gen-cordis-api.ts new file mode 100644 index 0000000000..34583d2ead --- /dev/null +++ b/scripts/gen-cordis-api.ts @@ -0,0 +1,247 @@ +/** + * Generate (and verify) the runtime cordis API catalog the `cordis_inspect` + * tool serves to the model: packages/cordis/tool-cordis/src/api-catalog.ts. + * + * The artifact is the machine-readable sibling of docs/cordis-catalog: it + * reuses `collectServices` / `collectEvents` from `gen-cordis-catalog.ts` (the + * same JSDoc-completeness-enforcing AST walk), so the API the model reads at + * runtime and the API the docs render cannot diverge. Emitted as a typed + * TypeScript data module (not JSON): it compiles under the package tsconfig, + * passes lint and the export-JSDoc gate, and is trivially covered by import. + * + * The data is trimmed for a model-facing text surface: per service the + * `ctx.` name, the first sentence of the class doc, and the raw method + * signatures; per event the name, `@mode`, signature, and first sentence of + * doc; the SHAPES of every exported interface/type-alias the service + * signatures reference (transitively — so a model can see that e.g. a + * `BashRunResult.stdout` is `{ text, truncated }`, not a string); plus the + * curated inherited `ctx` surface shared with the docs catalog. Source + * pointers are dropped (a `file:line` means nothing to the model) and entries + * are sorted deterministically. + * + * `tsx scripts/gen-cordis-api.ts` → write the artifact + * `tsx scripts/gen-cordis-api.ts --check` → exit 1 if the committed file is + * stale (CI / pre-push gate) + */ + +import { globSync, readFileSync, writeFileSync } from 'node:fs' +import { resolve } from 'node:path' +import ts from 'typescript' +import { collectEvents, collectServices, INHERITED_SERVICES } from './gen-cordis-catalog.ts' + +const root = resolve(import.meta.dirname, '..') +const OUT = 'packages/cordis/tool-cordis/src/api-catalog.ts' + +/** Declarations longer than this render as a truncated stub — a shape the model cannot skim teaches nothing. */ +const MAX_DECL_CHARS = 1500 + +/** The first sentence of a (possibly multi-line) JSDoc prose block. */ +function firstSentence(doc: string): string { + const line = doc.split('\n', 1)[0] ?? '' + const match = /^(.*?[.!?])(?:\s|$)/.exec(line) + return (match?.[1] ?? line).trim() +} + +/** Render a string as a single-quoted, lint-clean TS literal. */ +function quote(value: string): string { + return `'${value.replace(/\\/g, '\\\\').replace(/'/g, '\\\'').replace(/\n/g, '\\n')}'` +} + +/** + * Every exported `interface` / `type` declaration under `packages///src`, + * printed without comments, keyed by name. A name declared in more than one + * package (e.g. each plugin's `Config`) is ambiguous and dropped entirely — + * serving the wrong package's shape is worse than serving none. + */ +function collectTypeDecls(scanRoot: string = root): Map { + const printer = ts.createPrinter({ removeComments: true }) + const decls = new Map() + const ambiguous = new Set() + for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).sort()) { + const abs = resolve(scanRoot, rel) + const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true) + for (const stmt of sf.statements) { + if (!ts.isInterfaceDeclaration(stmt) && !ts.isTypeAliasDeclaration(stmt)) continue + if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) continue + const name = stmt.name.text + if (decls.has(name)) { + ambiguous.add(name) + continue + } + const printed = printer.printNode(ts.EmitHint.Unspecified, stmt, sf).replace(/\r/g, '') + decls.set(name, printed.length > MAX_DECL_CHARS + ? `${printed.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */` + : printed) + } + } + for (const name of ambiguous) decls.delete(name) + return decls +} + +/** + * The transitive closure of type names referenced by the seed texts: every + * collected declaration whose name appears (word-bounded) in a seed or in an + * already-included declaration, sorted by name. + */ +function referencedTypes(seeds: string[], decls: Map): { name: string; declaration: string }[] { + const included = new Map() + let frontier = seeds + while (frontier.length > 0) { + const next: string[] = [] + for (const [name, declaration] of decls) { + if (included.has(name)) continue + const pattern = new RegExp(`\\b${name}\\b`) + if (frontier.some(text => pattern.test(text))) { + included.set(name, declaration) + next.push(declaration) + } + } + frontier = next + } + return [...included].map(([name, declaration]) => ({ name, declaration })).sort((a, b) => a.name.localeCompare(b.name)) +} + +/** Render the whole generated module (pure, deterministic given sorted collector output). */ +function render(): string { + const services = collectServices() + const events = collectEvents().sort((a, b) => a.name.localeCompare(b.name)) + const types = referencedTypes(services.flatMap(service => service.methods), collectTypeDecls()) + const lines: string[] = [ + '/**', + ' * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run', + ' * `pnpm run gen-cordis-api` to regenerate (freshness-gated by', + ' * `pnpm run verify-cordis-api` in doc-sync).', + ' *', + ' * The machine-readable cordis API catalog `cordis_inspect` serves to the', + ' * model: harness services (summary + public method signatures), harness', + ' * events (mode + signature), and the inherited `ctx` surface. Produced by', + ' * the same AST walk as docs/cordis-catalog, so this data and the rendered', + ' * docs cannot diverge.', + ' *', + ' * @module @deepseek-ai/dsh-tool-cordis/api-catalog', + ' */', + '', + '/** One harness `ctx.` service: its one-line summary and public method signatures. */', + 'export interface ServiceApiEntry {', + ' /** The `ctx.` name, e.g. `tools`. */', + ' key: string', + ' /** First sentence of the service class JSDoc. */', + ' summary: string', + ' /** Public method signatures, bodies stripped, in source order. */', + ' methods: readonly string[]', + '}', + '', + '/** One harness event: its dispatch mode, exact signature, and one-line summary. */', + 'export interface EventApiEntry {', + ' /** The scoped event name, e.g. `agent/status`. */', + ' name: string', + ' /** The dispatch mode from the declaration\'s `@mode` tag. */', + ' mode: string', + ' /** The exact listener signature, whitespace-normalized. */', + ' signature: string', + ' /** First sentence of the event JSDoc. */', + ' summary: string', + '}', + '', + '/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */', + 'export interface InheritedApiEntry {', + ' /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */', + ' name: string', + ' /** One-line summary of what the member does. */', + ' summary: string', + '}', + '', + '/** One named type shape the service signatures reference. */', + 'export interface TypeApiEntry {', + ' /** The exported type/interface name, e.g. `BashRunResult`. */', + ' name: string', + ' /** The full declaration text, comments stripped. */', + ' declaration: string', + '}', + '', + '/** Every harness `ctx.` service, sorted by key. */', + 'export const SERVICE_API: readonly ServiceApiEntry[] = [', + ] + for (const service of services) { + lines.push(' {') + lines.push(` key: ${quote(service.key)},`) + lines.push(` summary: ${quote(firstSentence(service.doc))},`) + if (service.methods.length === 0) { + lines.push(' methods: [],') + } else { + lines.push(' methods: [') + for (const method of service.methods) lines.push(` ${quote(method)},`) + lines.push(' ],') + } + lines.push(' },') + } + lines.push( + ']', + '', + '/** Every harness event, sorted by name. */', + 'export const EVENT_API: readonly EventApiEntry[] = [', + ) + for (const event of events) { + lines.push(' {') + lines.push(` name: ${quote(event.name)},`) + lines.push(` mode: ${quote(event.mode)},`) + lines.push(` signature: ${quote(event.signature)},`) + lines.push(` summary: ${quote(firstSentence(event.doc))},`) + lines.push(' },') + } + lines.push( + ']', + '', + '/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */', + 'export const TYPE_API: readonly TypeApiEntry[] = [', + ) + for (const type of types) { + lines.push(' {') + lines.push(` name: ${quote(type.name)},`) + lines.push(` declaration: ${quote(type.declaration)},`) + lines.push(' },') + } + lines.push( + ']', + '', + '/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */', + 'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [', + ) + for (const inherited of INHERITED_SERVICES) { + lines.push(` { name: ${quote(inherited.name)}, summary: ${quote(inherited.summary)} },`) + } + lines.push(']', '') + return lines.join('\n') +} + +/** CLI entry: default writes the artifact, `--check` fails if the committed + * copy 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() + if (process.argv.includes('--check')) { + let committed: string | null = null + try { + committed = readFileSync(resolve(root, OUT), 'utf8') + } catch { + // Only ENOENT (not yet generated) is expected; a present-but-unreadable + // file is not a state this repo produces. Either way the remedy is the + // same — regenerate — so treat a read failure as "stale". + committed = null + } + if (committed === content) { + console.log(`gen-cordis-api: ${OUT} is up to date.`) + process.exit(0) + } + console.error(`gen-cordis-api: ${OUT} is stale. Run \`pnpm run gen-cordis-api\` and commit ${OUT}.`) + process.exit(1) + } + + writeFileSync(resolve(root, OUT), content) + console.log(`gen-cordis-api: wrote ${OUT}.`) +} + +// Run only when invoked as a script, not when imported by a test. +if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) { + main() +} diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 6220006ede..9b8141807e 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -327,7 +327,7 @@ const INHERITED_EVENTS: InheritedEntry[] = [ { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' }, ] -const INHERITED_SERVICES: InheritedEntry[] = [ +export const INHERITED_SERVICES: InheritedEntry[] = [ { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:29' }, { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:29' }, { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:144' }, From e51e58e9934cc3127854f0370ca918d3c0a01bad Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:50:12 +0800 Subject: [PATCH 083/119] chore: register the cordis group across repo gates and docs Everything outside the package and example that a new top-level group and a new demo touch: GROUP_ORDER in gen-module-graph and gen-doc-graphs (plus the tools-service consumers list, the APP_EXAMPLES entry, and the graph-atlas label/mode rows), the knip e2e entries, the packages/README group row, the AGENTS.md layout and demo lines, and the regenerated module-graph / config-catalog / graph-atlas / capability-seams / composition artifacts. AGENTS.md and examples/AGENTS.md word-budget ceilings rise to current+5% (1802 / 653): the new group and demo rows are genuine additions to both docs, not condensable restatements. --- AGENTS.md | 2 ++ docs/capability-seams.md | 4 ++- docs/config-catalog.md | 18 +++++++++++++ docs/graph-atlas.md | 1 + docs/module-graph.md | 5 ++++ examples/AGENTS.md | 1 + examples/README.md | 6 +++++ examples/cordis-agent/composition.md | 40 ++++++++++++++++++++++++++++ knip.json | 1 + packages/README.md | 1 + scripts/doc-budgets.manifest.json | 4 +-- scripts/gen-doc-graphs.ts | 13 ++++++++- scripts/gen-module-graph.ts | 1 + 13 files changed, 93 insertions(+), 4 deletions(-) create mode 100644 examples/cordis-agent/composition.md diff --git a/AGENTS.md b/AGENTS.md index 1ef6af2ba0..c272ad5dda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai subagent/ subagent seam + spawn/fork/ACP backends + delegation tool todo/ the todo_write tool guard/ loop-hygiene plugins + cordis/ self-referential toolset: the agent inspects/mounts plugins in its own runtime hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends ui/ ACP bridge + app-boot glue + the stdio/ACP app bins @@ -48,6 +49,7 @@ pnpm run hygiene # knip + publint + workspace constraints + NodeNext cons pnpm run doc-sync # all documentation gates; see the doc-sync script in package.json pnpm run demo:echo # mock-model REPL, no key needed pnpm run demo:repl # real REPL coding agent (needs DEEPSEEK_API_KEY) +pnpm run demo:cordis # self-referential demo: the agent modifies its own runtime (needs key) pnpm run demo:acp # ACP server agent (needs DEEPSEEK_API_KEY) ``` diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 12ce8033b9..b85fa40305 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -31,6 +31,7 @@ flowchart LR pkg_tool_web["tool-web"] svc_tools["ctx.tools
Tool registry and execution waterfall"] pkg_tool_bash["tool-bash"] + pkg_tool_cordis["tool-cordis"] pkg_tool_subagent["tool-subagent"] pkg_tool_todo["tool-todo"] svc_agents["ctx.agents
Agent registry"] @@ -121,6 +122,7 @@ flowchart LR svc_tools --> pkg_acp svc_tools --> pkg_agent_loop svc_tools --> pkg_tool_bash + svc_tools --> pkg_tool_cordis svc_tools --> pkg_tool_fs svc_tools --> pkg_tool_subagent svc_tools --> pkg_tool_todo @@ -135,7 +137,7 @@ flowchart LR | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. | | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. | | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. | -| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | +| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 2429fe3163..d466bff4c0 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -670,6 +670,24 @@ export interface Config { Source: [`packages/core/system-prompt/src/index.ts:179`](../packages/core/system-prompt/src/index.ts) +## `@deepseek-ai/dsh-tool-cordis` + +Requires: `tools` + +```ts config-catalog +/** Config for the tool-cordis plugin: the sandbox evaluation bound. */ +export interface Config { + /** + * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm + * before evaluation is aborted (default 5000). An async body escapes this + * bound — see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance. + */ + vmTimeoutMs?: number +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts:49`](../packages/cordis/tool-cordis/src/index.ts) + ## `@deepseek-ai/dsh-tool-fs` Requires: `tools` · `fs` · `systemPrompt` diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md index 2a3d674bec..60de01ef81 100644 --- a/docs/graph-atlas.md +++ b/docs/graph-atlas.md @@ -14,6 +14,7 @@ The process decision behind this index is recorded in [the documentation graph R | [capability seams and core services](capability-seams.md) | `hybrid generated` | | [echo-agent app composition](../examples/echo-agent/composition.md) | `hybrid generated` | | [coding-agent app composition](../examples/coding-agent/composition.md) | `hybrid generated` | +| [cordis-agent app composition](../examples/cordis-agent/composition.md) | `hybrid generated` | | [acp-agent app composition](../examples/acp-agent/composition.md) | `hybrid generated` | | [event producer/consumer matrix](event-producer-consumer.md) | `hybrid generated` | | [agent turn and step lifecycle](agent-lifecycle.md) | `curated` | diff --git a/docs/module-graph.md b/docs/module-graph.md index 1e4e70151f..beabf14c69 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -61,6 +61,9 @@ flowchart TD subgraph group_todo["packages/todo"] pkg_tool_todo["tool-todo"] end + subgraph group_cordis["packages/cordis"] + pkg_tool_cordis["tool-cordis"] + end subgraph group_hooks["packages/hooks"] pkg_hook_protocol["hook-protocol"] pkg_hooks_claude["hooks-claude"] @@ -164,6 +167,7 @@ flowchart TD pkg_tool_todo --> pkg_agent pkg_tool_todo --> pkg_session pkg_tool_todo --> pkg_tools + pkg_tool_cordis --> pkg_tools pkg_hooks_codex --> pkg_agent pkg_hooks_codex --> pkg_hook_protocol pkg_hooks_codex --> pkg_llm @@ -264,6 +268,7 @@ flowchart TD | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | +| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`tools`](../packages/core/tools) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | diff --git a/examples/AGENTS.md b/examples/AGENTS.md index 6c1cc717df..94597371cf 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -21,6 +21,7 @@ A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_P |---|---|---| | `echo-agent` | `tests/echo.e2e.ts` — boots the real `cordis.yml`, drives the echo tool round-trip and the direct canned reply | **N/A — keyless by nature** (the `mock-echo` model has no real provider) | | `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified | +| `cordis-agent` | `tests/keyless-smoke.e2e.ts` — boots the real tree incl. `@deepseek-ai/dsh-tool-cordis` by package name; the tool logic is unit-tested in `packages/cordis/tool-cordis` | `tests/cordis-tools.e2e.ts` — real model mounts a listener (tagged line fires), builds+calls its own tool, composes two mounts via provide/inject | | `acp-agent` | `pnpm run test:snapshot` — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); `tests/acp.e2e.ts` also asserts stdout purity without a key | `tests/acp.e2e.ts` — real ACP prompt, verifies a file the agent wrote; `tests/hooks.e2e.ts` — a real `PreToolUse` hook blocks bash, verifies the file is NOT written | See [the root AGENTS.md](../AGENTS.md) for repo-wide conventions and [docs/architecture.md](../docs/architecture.md) for the design. diff --git a/examples/README.md b/examples/README.md index 1e3134ba2d..c308df73e1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,6 +19,12 @@ A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + th Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details. +## cordis-agent + +The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. + +Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset RFC](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats. + ## acp-agent An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. diff --git a/examples/cordis-agent/composition.md b/examples/cordis-agent/composition.md new file mode 100644 index 0000000000..6822129c26 --- /dev/null +++ b/examples/cordis-agent/composition.md @@ -0,0 +1,40 @@ + + +# Cordis Agent App Composition + +The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its own runtime and mount/unmount plugins into it. + +```mermaid +flowchart LR + cfg["examples/cordis-agent
cordis.yml"] + plugin_cordis_hmr["hmr
@cordisjs/plugin-hmr"] + cfg --> plugin_cordis_hmr + plugin_cordis_llm_deepseek["llm-deepseek
@deepseek-ai/dsh-llm-deepseek"] + cfg --> plugin_cordis_llm_deepseek + plugin_cordis_bash["bash
@deepseek-ai/dsh-bash-local"] + cfg --> plugin_cordis_bash + plugin_cordis_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-agent"] + cfg --> plugin_cordis_stdio_agent + plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"] + plugin_cordis_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] + plugin_cordis_stdio_agent --> frontdoor_stdio["readline UI
console logger
pre-created main agent"] + bundle_agent_core --> spine_llm["ctx.llm"] + bundle_agent_core --> spine_sessions["ctx.sessions"] + bundle_agent_core --> spine_tools["ctx.tools + tool-bash"] + bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"] + plugin_cordis_tool_cordis["tool-cordis
@deepseek-ai/dsh-tool-cordis"] + cfg --> plugin_cordis_tool_cordis +``` + +| Plugin id | Package / module | +| --- | --- | +| `hmr` | `@cordisjs/plugin-hmr` | +| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | +| `bash` | `@deepseek-ai/dsh-bash-local` | +| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` | +| `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` | + +Source config: [`examples/cordis-agent/cordis.yml`](cordis.yml). + +Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source. diff --git a/knip.json b/knip.json index 407f892775..198cad3cce 100644 --- a/knip.json +++ b/knip.json @@ -8,6 +8,7 @@ "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" ], diff --git a/packages/README.md b/packages/README.md index bc09826777..d7c3c4caf1 100644 --- a/packages/README.md +++ b/packages/README.md @@ -19,6 +19,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface | | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface | +| [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | | [`ui/`](ui/README.md) | Editor/client integration surfaces (the ACP bridge) + the app packages | Product — stable surface | diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 337fc57763..8cadde12e9 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,11 +1,11 @@ { - "AGENTS.md": 1691, + "AGENTS.md": 1802, "docs/AGENTS.md": 1315, "docs/architecture.md": 1640, "docs/cordis-primer.md": 550, "docs/defensive-patterns.md": 550, "docs/testing.md": 800, - "examples/AGENTS.md": 610, + "examples/AGENTS.md": 653, "packages/AGENTS.md": 450, "packages/README.md": 610 } diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 14396a6645..d8d320df33 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -75,6 +75,7 @@ const GROUP_ORDER = [ 'subagent', 'web', 'todo', + 'cordis', 'hooks', 'session-persistence', 'support', @@ -121,7 +122,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'tools', title: 'Tool registry and execution waterfall', mode: 'core', - consumers: ['agent-loop', 'tool-bash', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'], + consumers: ['agent-loop', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'], note: 'Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute.', }, { @@ -409,6 +410,14 @@ const APP_EXAMPLES = [ config: 'examples/coding-agent/cordis.yml', summary: 'The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.', }, + { + id: 'cordis', + rel: 'examples/cordis-agent/composition.md', + title: 'Cordis Agent App Composition', + label: 'examples/cordis-agent', + config: 'examples/cordis-agent/cordis.yml', + summary: 'The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its own runtime and mount/unmount plugins into it.', + }, { id: 'acp', rel: 'examples/acp-agent/composition.md', @@ -718,6 +727,7 @@ function renderIndex(docs: GraphDoc[]): string { 'docs/capability-seams.md': 'capability seams and core services', 'examples/echo-agent/composition.md': 'echo-agent app composition', 'examples/coding-agent/composition.md': 'coding-agent app composition', + 'examples/cordis-agent/composition.md': 'cordis-agent app composition', 'examples/acp-agent/composition.md': 'acp-agent app composition', 'docs/event-producer-consumer.md': 'event producer/consumer matrix', 'docs/agent-lifecycle.md': 'agent turn and step lifecycle', @@ -728,6 +738,7 @@ function renderIndex(docs: GraphDoc[]): string { 'docs/capability-seams.md': 'hybrid generated', 'examples/echo-agent/composition.md': 'hybrid generated', 'examples/coding-agent/composition.md': 'hybrid generated', + 'examples/cordis-agent/composition.md': 'hybrid generated', 'examples/acp-agent/composition.md': 'hybrid generated', 'docs/event-producer-consumer.md': 'hybrid generated', 'docs/agent-lifecycle.md': 'curated', diff --git a/scripts/gen-module-graph.ts b/scripts/gen-module-graph.ts index fe39d325f8..dc66dc843e 100644 --- a/scripts/gen-module-graph.ts +++ b/scripts/gen-module-graph.ts @@ -47,6 +47,7 @@ const GROUP_ORDER = [ 'web', 'timeout', 'todo', + 'cordis', 'hooks', 'session-persistence', 'support', From db4576951320b1d7e73c320c8519a4f9a6657012 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:51:24 +0800 Subject: [PATCH 084/119] feat(tool-cordis): Node-API traps + fs/web capability routing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sandbox deliberately provides no Node API, and now says so instead of letting a bare ReferenceError teach nothing: require, the timers, and fetch are callable traps whose error redirects to the cordis alternative (inject: ['fs'] + ctx.fs, ['web'] + ctx.web, ['bash'] + ctx.bash, ['timer'] + ctx.setTimeout — a fiber effect, unwound on unmount). Only function-shaped globals are trapped; process/Buffer stay undefined so typeof feature probes stay inert. The mount description and the demo persona state the routing rule, and the demo mounts ctx.fs (local provider) and ctx.web (seam + keyless local fetch provider) so agent-built plugins have real capabilities to build on. Live-validated: a model that reached for Node setTimeout self-corrected to inject: ['timer'] in one step and built a working ctx.web fetch tool. --- docs/tool-catalog.md | 2 +- examples/README.md | 2 +- examples/cordis-agent/README.md | 2 +- examples/cordis-agent/composition.md | 9 +++ examples/cordis-agent/cordis.yml | 27 +++++++-- packages/cordis/tool-cordis/src/index.ts | 9 ++- packages/cordis/tool-cordis/src/sandbox.ts | 59 ++++++++++++++++--- .../cordis/tool-cordis/tests/mount.spec.ts | 37 +++++++++++- 8 files changed, 129 insertions(+), 18 deletions(-) diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index e77716f736..f0a3fab35d 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`; there is no `require`, `process`, `Buffer`, or network. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. ```json { diff --git a/examples/README.md b/examples/README.md index c308df73e1..c86f83022a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -21,7 +21,7 @@ Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a ## cordis-agent -The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. +The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. The `ctx.fs`/`ctx.web` services ride along provider-only, as the capabilities those plugins build on. Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset RFC](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats. diff --git a/examples/cordis-agent/README.md b/examples/cordis-agent/README.md index ba9365498b..953533d35b 100644 --- a/examples/cordis-agent/README.md +++ b/examples/cordis-agent/README.md @@ -1,6 +1,6 @@ # cordis-agent -The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). +The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). ## Run it diff --git a/examples/cordis-agent/composition.md b/examples/cordis-agent/composition.md index 6822129c26..015bec724e 100644 --- a/examples/cordis-agent/composition.md +++ b/examples/cordis-agent/composition.md @@ -14,6 +14,12 @@ flowchart LR cfg --> plugin_cordis_llm_deepseek plugin_cordis_bash["bash
@deepseek-ai/dsh-bash-local"] cfg --> plugin_cordis_bash + plugin_cordis_fs_local["fs-local
@deepseek-ai/dsh-fs-local"] + cfg --> plugin_cordis_fs_local + plugin_cordis_web["web
@deepseek-ai/dsh-web"] + cfg --> plugin_cordis_web + plugin_cordis_web_fetch_local["web-fetch-local
@deepseek-ai/dsh-web-fetch-local"] + cfg --> plugin_cordis_web_fetch_local plugin_cordis_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-agent"] cfg --> plugin_cordis_stdio_agent plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"] @@ -32,6 +38,9 @@ flowchart LR | `hmr` | `@cordisjs/plugin-hmr` | | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | | `bash` | `@deepseek-ai/dsh-bash-local` | +| `fs-local` | `@deepseek-ai/dsh-fs-local` | +| `web` | `@deepseek-ai/dsh-web` | +| `web-fetch-local` | `@deepseek-ai/dsh-web-fetch-local` | | `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` | | `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` | diff --git a/examples/cordis-agent/cordis.yml b/examples/cordis-agent/cordis.yml index b5e08c8325..65d5e6eb36 100644 --- a/examples/cordis-agent/cordis.yml +++ b/examples/cordis-agent/cordis.yml @@ -36,6 +36,23 @@ config: timeoutMs: 60000 +# Filesystem service for mounted plugins (ctx.fs) — the local provider only. +# The model-facing read/write/edit tools stay unmounted on purpose: this demo +# is about the agent building its own tools over the services. +- id: fs-local + name: '@deepseek-ai/dsh-fs-local' + config: + cwd: !!js process.cwd() + +# Web service for mounted plugins (ctx.web): the seam plus the anonymous local +# fetch provider (keyless). No search provider is loaded — ctx.web search +# calls fail loud until a deployment adds one. +- id: web + name: '@deepseek-ai/dsh-web' + +- id: web-fetch-local + name: '@deepseek-ai/dsh-web-fetch-local' + # The stdio chat app: the whole spine + front-door cluster, configured for the # self-referential demo driving a pre-created `main` agent. - id: stdio-agent @@ -54,10 +71,12 @@ `events` sections document the service methods, type shapes, and events your plugin code can use), cordis_mount to add a plugin (an event listener, a brand-new tool for yourself, or a service other mounts - inject), cordis_unmount to clean one up. Prefer small single-purpose - plugins, prefer plain notification events over waterfall events unless - you intend to intercept, and unmount what you no longer need. Report - results briefly. + inject), cordis_unmount to clean one up. In mounted code, NEVER use Node + built-ins (require/setTimeout/fetch) — use the runtime's cordis services + via inject: fs, web, bash, and timer (ctx.setTimeout). Prefer small + single-purpose plugins, prefer plain notification events over waterfall + events unless you intend to intercept, and unmount what you no longer + need. Report results briefly. # The self-referential cordis toolset (loaded after the app so ctx.tools exists). - id: tool-cordis diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index d4492b4768..de028b384a 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -152,8 +152,13 @@ export function apply(ctx: Context, config: Config): void { + 'Everything registered inside `apply` is cleaned up automatically on unmount. ' + 'Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness ' + 'terminal), `harness.defineTool`, `harness.registerTool`, ' - + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`; ' - + 'there is no `require`, `process`, `Buffer`, or network. ' + + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`. ' + + 'Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, ' + + 'never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect ' + + 'errors; `process` and `Buffer` are undefined. Instead use inject: [\'fs\'] + ctx.fs for ' + + 'files, inject: [\'web\'] + ctx.web for HTTP, inject: [\'bash\'] + ctx.bash for processes, ' + + 'and inject: [\'timer\'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, ' + + 'auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. ' + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). ' + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a ' + 'trailing `next` callback which MUST be called — returning without `next()` ' diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts index 4d3eb16dfc..add858f3ce 100644 --- a/packages/cordis/tool-cordis/src/sandbox.ts +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -1,10 +1,16 @@ /** * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose * globals are a tagged write-through console, the `harness` registration - * helpers, and the encoding primitives a bare vm context lacks. The sandbox - * guards against ACCIDENTAL global pollution only — it is not a security - * boundary; the `ctx` a mounted plugin's `apply` later receives is the real, - * fully privileged runtime handle, and that is the point of the toolset. + * helpers, the encoding primitives a bare vm context lacks, and callable traps + * over the Node APIs the sandbox deliberately withholds. Capability access is + * routed through cordis services, never Node built-ins: filesystem work goes + * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`, + * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount) + * — so everything a mounted plugin does stays inspectable and disposable. The + * sandbox guards against ACCIDENTAL global pollution only — it is not a + * security boundary; the `ctx` a mounted plugin's `apply` later receives is + * the real, fully privileged runtime handle, and that is the point of the + * toolset. * * @module @deepseek-ai/dsh-tool-cordis/sandbox */ @@ -60,19 +66,58 @@ function patchDualRealmInstanceof(sandbox: object): void { patch({ Object, Array, Function, Error, TypeError, RangeError, SyntaxError, Promise, RegExp, Date, Map, Set }) } +const TIMER_REDIRECT + = 'Node timers are unavailable. Use the cordis timer service instead: declare inject: [\'timer\'] on your plugin ' + + 'and call ctx.setTimeout / ctx.setInterval — those are fiber effects, cleaned up automatically on unmount.' + +/** + * The callable Node APIs the sandbox deliberately disables, each mapped to the + * cordis alternative its trap error names. Only FUNCTION-shaped globals are + * trapped — a data-shaped global like `process` stays `undefined`, because a + * throwing accessor would detonate the common `typeof process` feature probe + * at resolution time. + */ +const NODE_API_REDIRECTS: Record = { + require: + 'Node modules are unavailable. Use the cordis services on ctx instead — e.g. inject: [\'fs\'] for files, ' + + '[\'web\'] for HTTP, [\'bash\'] for processes; cordis_inspect what:"api" lists what THIS runtime provides.', + setTimeout: TIMER_REDIRECT, + setInterval: TIMER_REDIRECT, + setImmediate: TIMER_REDIRECT, + clearTimeout: TIMER_REDIRECT, + clearInterval: TIMER_REDIRECT, + fetch: + 'Network access goes through the cordis web service: declare inject: [\'web\'] and call ctx.web ' + + '(see cordis_inspect what:"api" for its methods).', +} + +/** Build the trap functions for {@link NODE_API_REDIRECTS}: calling one throws the redirect. */ +function nodeApiTraps(): Record never> { + const traps: Record never> = {} + for (const [name, redirect] of Object.entries(NODE_API_REDIRECTS)) { + traps[name] = () => { + throw new Error(`${name} is not available in the mount sandbox — ${redirect}`) + } + } + return traps +} + /** * Build the vm context one `cordis_mount` call evaluates in: the tagged - * console, the `harness` registration helpers, the encoding primitives, and - * the dual-realm `instanceof` patch, already `createContext`-ed. + * console, the `harness` registration helpers, the encoding primitives, the + * Node-API traps, and the dual-realm `instanceof` patch, already + * `createContext`-ed. * @param id - the mount id (`dyn-`), used as the console tag and filename stem. * @returns the contextified sandbox object to pass to {@link evaluateMountCode}. */ export function createSandbox(id: string): object { const sandbox = { + ...nodeApiTraps(), console: taggedConsole(id), harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool }, // Web APIs absent from fresh vm contexts — made available so the model - // can encode/decode base64 without Buffer (which is also absent). + // can encode/decode base64 without Buffer (which is also absent). Host + // closures over Buffer, never Buffer itself. btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'), atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'), TextEncoder, diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 5bdde09b53..03038f818c 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -284,12 +284,12 @@ describe('cordis_mount', () => { expect(retry.isError).toBe(false) }) - it('isolates sandbox globals: no process/require, and globalThis writes do not leak to the host', async () => { + it('isolates sandbox globals: no process/Buffer, and globalThis writes do not leak to the host', async () => { const ctx = await setup() const result = await call(ctx, 'cordis_mount', { code: ` globalThis.__cordis_tool_leak = 'leaked' - return { name: 'probe-' + typeof process + '-' + typeof require, apply(ctx) {} } + return { name: 'probe-' + typeof process + '-' + typeof Buffer, apply(ctx) {} } `, }) expect(result.isError).toBe(false) @@ -297,6 +297,39 @@ describe('cordis_mount', () => { expect((globalThis as Record).__cordis_tool_leak).toBeUndefined() }) + it.each([ + ['require(\'fs\')', 'require is not available in the mount sandbox', 'inject: [\'fs\']'], + ['setTimeout(() => {}, 5)', 'setTimeout is not available in the mount sandbox', 'ctx.setTimeout'], + ['fetch(\'https://example.com\')', 'fetch is not available in the mount sandbox', 'ctx.web'], + ])('traps the Node API call %s with a redirect to the cordis alternative', async (invocation, trapMessage, redirect) => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: `${invocation}\nreturn (ctx) => {}` }) + expect(result.isError).toBe(true) + expect(text(result)).toContain(trapMessage) + expect(text(result)).toContain(redirect) + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('lets a mounted plugin schedule through the cordis timer service (inject: [\'timer\'])', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'ticker', + inject: ['timer'], + apply(ctx) { + ctx.setTimeout(() => console.log('tick'), 10) + }, + } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('state: active') + await new Promise(resolve => setTimeout(resolve, 50)) + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tick') + }) + it('provides btoa/atob and the tagged console variants inside the sandbox', async () => { const ctx = await setup() const log = vi.spyOn(console, 'log').mockImplementation(() => {}) From a500c791f7faa2a29437a8a446f73541e0f056fb Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 14:51:35 +0800 Subject: [PATCH 085/119] fix(tool-cordis): normalize the JSON-Schema dialect at the defineTool boundary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Field sessions showed models writing tool schemas in the JSON-Schema dialect by strong prior — type: 'integer', required: false, then the full { type:'object', properties, required: [...] } wrapper — and the rejection text itself pushed a nearly-correct DSL attempt BACK to raw JSON Schema: one stats tool cost three consecutive schema errors before mounting. The boundary now normalizes wherever the input has exactly one meaning (wrapper unwrapped with the required array becoming per-property flags at any nesting level, integer → number, required: false → optional, all rebuilt as fresh host-realm objects) and rejects only genuinely meaningless input, enumerating the valid vocabulary in the error. Re-running the failing session mounts first-try. The mount description documents both accepted forms. --- ...6-07-08-self-referential-cordis-toolset.md | 4 +- docs/tool-catalog.md | 2 +- packages/cordis/tool-cordis/src/guard.ts | 102 ++++++++++++------ packages/cordis/tool-cordis/src/index.ts | 5 +- .../cordis/tool-cordis/tests/mount.spec.ts | 68 ++++++++++-- 5 files changed, 132 insertions(+), 49 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 95cb12b571..14e05b0afd 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -32,7 +32,7 @@ Sandbox globals are deliberately small: a tagged write-through `console` (`[cord Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **Guarded registration**: the `ctx` a mounted plugin receives is a proxy whose `tools.register` accepts only definitions returned by `harness.defineTool` (a marker symbol), so every dynamic tool passes SchemaSpec validation and realm normalization; everything else on `ctx` passes through with correct `this` binding, which is what keeps cross-mount `provide`/`inject` working. -Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found): JSON Schema where the SchemaSpec DSL is expected gets a ✗/✓ example pair; an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. +Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. ### The dynamic group and mount lifecycle @@ -79,6 +79,6 @@ The correctness investment therefore goes where it pays for every capability at The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` vetoes the chain, so a mounted listener can lobotomize the agent's own tool dispatch ([waterfall semantics](../../../cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume. -The instructive boundary errors were not guessed — they were written against a live self-design session in which a real model was asked to build itself coding tools. That session surfaced the failure modes now mitigated: the model closed a returned plugin object with `});` and got only a bare `Unexpected token ')'` it retried blind; it hit a false-positive "this is TypeScript" hint because a description string contained the word "as"; and, most costly, it guessed a bash run's `stdout` was a string and burned six steps building throwaway debug tools to discover it is `{ text, truncated }`. The fixes — source-line-plus-caret parse errors, line-scoped TypeScript detection, the type-shape closure in the API catalog, and the redirect traps — cut a second session from dozens of tool calls with repeated errors to a first-try success on every capability, including a model that hit a Node-`setTimeout` trap and self-corrected to `inject: ['timer']` in one step. +The instructive boundary errors were not guessed — they were written against live self-design sessions in which a real model was asked to build itself coding tools. Those sessions surfaced the failure modes now mitigated: the model closed a returned plugin object with `});` and got only a bare `Unexpected token ')'` it retried blind; it hit a false-positive "this is TypeScript" hint because a description string contained the word "as"; it guessed a bash run's `stdout` was a string and burned six steps building throwaway debug tools to discover it is `{ text, truncated }`; and it wrote tool schemas in the JSON-Schema dialect (`type: 'integer'`, `required: false`, then the full wrapper) three rejections in a row — the rejection text itself pushing it from a nearly-correct DSL attempt back to raw JSON Schema. The fixes — source-line-plus-caret parse errors, line-scoped TypeScript detection, the type-shape closure in the API catalog, the redirect traps, and schema-dialect normalization in place of rejection — cut later sessions from dozens of tool calls with repeated errors to a first-try success on every capability, including a model that hit a Node-`setTimeout` trap and self-corrected to `inject: ['timer']` in one step. Coverage is named per tier: package unit specs drive the three tools through a real `ToolRegistry` on a real fiber tree (the mount success/failure family, vm isolation, dual-realm `instanceof`, realm normalization against the real `isJsonValue`, the SchemaSpec and raw-registration rejections, the Node-API traps, the cross-mount provide/inject matrix, catalog-backed `api`/`events` rendering, config validation, presenters, quiescent unmount, and the HMR cascade), a `MockAdapter` loop test proves a tool mounted in one step is dispatchable in the next, and the example carries a keyless Loader smoke plus a with-key smoke that world-verifies a live model mounting a listener, building its own tool, and composing two mounts. No snapshot scenario is added: the toolset ships in no ACP-served app, so it changes no editor-facing transcript, and its presenters are unit-tested pure functions — adding it to the ACP example solely for a golden would rewrite the pinned request-header tool set of every recorded scenario. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index f0a3fab35d..91c2104a13 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. ```json { diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 09d804771f..998997a8f9 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -1,19 +1,27 @@ /** * The registration boundary between sandboxed mount code and the real runtime: - * SchemaSpec validation with teaching errors, the marker-guarded - * `harness.defineTool` / `harness.registerTool` pair, the guarded `ctx` proxy a - * mounted plugin receives, and the plugin-shape helpers the mount lifecycle - * narrows sandbox return values with. + * SchemaSpec normalization + validation with teaching errors, the + * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the + * guarded `ctx` proxy a mounted plugin receives, and the plugin-shape helpers + * the mount lifecycle narrows sandbox return values with. * * Two realm facts drive the design. Objects built inside the vm carry the vm * realm's `Object.prototype`, and the session log's append-time plainness check * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects * foreign-realm data — so every dynamic tool's `execute` return is JSON - * round-tripped into the host realm before it reaches the registry. And a - * malformed tool schema must fail at REGISTRATION, not when a later request - * assembles it — so dynamic `ctx.tools.register` calls accept only definitions - * produced by the sandbox's `harness.defineTool`, which asserts the SchemaSpec - * DSL up front. + * round-tripped into the host realm before it reaches the registry, and the + * schema itself is rebuilt as fresh host-realm objects. And a malformed tool + * schema must fail at REGISTRATION, not when a later request assembles it — so + * dynamic `ctx.tools.register` calls accept only definitions produced by the + * sandbox's `harness.defineTool`, which normalizes `parameters` up front. + * + * Normalize, don't lecture, where the input has exactly one meaning: models + * write the JSON-Schema dialect by strong prior (the `{ type: 'object', + * properties, required: […] }` wrapper, `type: 'integer'`, `required: false`), + * and each rejection costs a model turn — so those convert to the SchemaSpec + * DSL silently, and only genuinely meaningless input (an unknown type, a + * non-boolean `required`) is rejected, with the error enumerating the valid + * vocabulary. * * @module @deepseek-ai/dsh-tool-cordis/guard */ @@ -24,6 +32,7 @@ import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools' const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool') const SCHEMA_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']) +const VALID_TYPES = '\'string\' | \'number\' | \'boolean\' | \'object\' | \'array\'' type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true } type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown } @@ -32,47 +41,70 @@ function isPlainRecord(value: unknown): value is Record { return Object.prototype.toString.call(value) === '[object Object]' } -/** Assert a sandbox-provided `parameters` value is a SchemaSpec object, with a teaching error for the common JSON-Schema mistake. */ -function assertSchemaSpec(value: unknown): void { +/** + * Normalize a sandbox-provided `parameters` value into a fresh host-realm + * SchemaSpec. Accepts the DSL directly, or the JSON-Schema-style + * `{ type: 'object', properties, required: […] }` wrapper models write by + * prior — the wrapper unwraps and its `required` array becomes per-property + * flags (see the module doc). + */ +function normalizeSchemaSpec(value: unknown, path = 'parameters'): Record { if (!isPlainRecord(value)) { - throw new Error('harness.defineTool parameters must be a SchemaSpec object') + throw new Error(`harness.defineTool ${path} must be a SchemaSpec object`) } + let entries = value + const requiredNames = new Set() if (value.type === 'object' && isPlainRecord(value.properties)) { - throw new Error( - 'harness.defineTool parameters use the SchemaSpec DSL (NOT JSON Schema).\n' - + ' ✗ { type: \'object\', properties: { name: { type: \'string\' } }, required: [\'name\'] }\n' - + ' ✓ { name: { type: \'string\', required: true } }\n' - + 'Remove the outer { type: \'object\', properties, required } wrapper; ' - + 'each key IS a property directly on the parameters object.', - ) + if (Array.isArray(value.required)) { + for (const name of value.required) requiredNames.add(name) + } + entries = value.properties } - for (const [key, prop] of Object.entries(value)) { - assertSchemaProp(prop, `parameters.${key}`) + const spec: Record = {} + for (const [key, prop] of Object.entries(entries)) { + spec[key] = normalizeSchemaProp(prop, `${path}.${key}`, requiredNames.has(key)) } + return spec } -function assertSchemaProp(value: unknown, path: string): void { +/** Normalize one property: `integer` → `number`, `required: false` → absent, nested wrappers unwrapped recursively. */ +function normalizeSchemaProp(value: unknown, path: string, forceRequired = false): Record { if (!isPlainRecord(value)) { throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`) } - if (!SCHEMA_TYPES.has(value.type)) { - throw new Error(`harness.defineTool ${path} must declare a valid type`) + const type = value.type === 'integer' ? 'number' : value.type + if (!SCHEMA_TYPES.has(type)) { + throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`) } - if (value.required !== undefined && value.required !== true) { - throw new Error(`harness.defineTool ${path}.required must be true when present`) + // On an object property a JSON-Schema-style `required` ARRAY names required + // children (handled by the nested unwrap below); everywhere else `required` + // must be a boolean, and `false` simply reads as optional. + const nestedRequiredArray = type === 'object' && Array.isArray(value.required) + if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) { + throw new Error(`harness.defineTool ${path}.required must be a boolean when present`) } + const prop: Record = { type } + if (forceRequired || value.required === true) prop.required = true + if (typeof value.description === 'string') prop.description = value.description + if (Array.isArray(value.enum)) prop.enum = [...value.enum as unknown[]] + if (value.default !== undefined) prop.default = value.default if (value.properties !== undefined) { - if (value.type !== 'object') { + if (type !== 'object') { throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`) } - assertSchemaSpec(value.properties) + // Re-wrap so the nested unwrap applies a nested `required` array too. + prop.properties = normalizeSchemaSpec( + { type: 'object', properties: value.properties, required: value.required }, + `${path}.properties`, + ) } if (value.items !== undefined) { - if (value.type !== 'array') { + if (type !== 'array') { throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`) } - assertSchemaProp(value.items, `${path}.items`) + prop.items = normalizeSchemaProp(value.items, `${path}.items`) } + return prop } function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition { @@ -87,17 +119,19 @@ function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition } /** - * The `harness.defineTool` handed into the sandbox: the real DSL, with the + * The `harness.defineTool` handed into the sandbox: the real DSL, with + * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema + * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the * tool's `execute` return normalized into the host realm via a JSON round-trip * (see the module doc). The round-trip also projects the return onto exactly * what the log would durably store, so a non-JSON-serializable return surfaces * as that one call's error instead of poisoning the turn. - * @param options - the standard `defineTool` options, with `parameters` asserted against the SchemaSpec DSL before the DSL sees them. + * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper. * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts. */ export function sandboxDefineTool(options: Parameters[0]): ToolDefinition { - assertSchemaSpec((options as { parameters?: unknown }).parameters) - const tool = defineTool(options) + const parameters = normalizeSchemaSpec((options as { parameters?: unknown }).parameters) + const tool = defineTool({ ...options, parameters } as Parameters[0]) const execute = tool.execute.bind(tool) return markDynamicTool({ ...tool, diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index de028b384a..7dff9b993d 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -143,7 +143,10 @@ export function apply(ctx: Context, config: Config): void { + 'events (see cordis_inspect what:"events"), or call ' + '`harness.registerTool(ctx, harness.defineTool({ name, description, parameters: ' + '{ text: { type: \'string\', required: true } }, async execute(args) { … } }))` ' - + 'to give yourself a new tool — it becomes callable on your NEXT step. A ' + + 'to give yourself a new tool — it becomes callable on your NEXT step. ' + + 'Tool parameters: each key IS a property — { type: \'string\'|\'number\'|\'boolean\'|\'object\'|\'array\', ' + + 'required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style ' + + '{ type: \'object\', properties, required: […] } wrapper and type \'integer\' are also accepted and normalized. A ' + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return ' + '[{ type: \'text\', text: someString }]` — never a bare string. ' + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and ' diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 03038f818c..543b38307f 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -60,39 +60,85 @@ describe('cordis_mount', () => { expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true) }) - it('rejects JSON Schema passed to harness.defineTool with the SchemaSpec teaching error', async () => { + it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => { + // The dialect models write by strong prior: the { type:'object', + // properties, required: […] } wrapper, `type: 'integer'`, and + // `required: false`. All of it has exactly one meaning — normalize instead + // of burning a model turn on a lecture. const ctx = await setup() const result = await call(ctx, 'cordis_mount', { code: ` return { - name: 'bad-json-schema-tool', + name: 'json-schema-tool', inject: ['tools'], apply(ctx) { harness.registerTool(ctx, harness.defineTool({ - name: 'bad_json_schema_tool', - description: 'bad', + name: 'json_schema_tool', + description: 'written in the JSON-Schema dialect', parameters: { type: 'object', - properties: { text: { type: 'string' } }, + properties: { + text: { type: 'string', description: 'the text' }, + count: { type: 'integer', default: 1 }, + mode: { type: 'string', enum: ['fast', 'slow'] }, + extra: { type: 'string', required: false }, + }, required: ['text'], }, - async execute() { return [{ type: 'text', text: 'bad' }] }, + async execute(args) { return [{ type: 'text', text: args.text + ':' + (args.count ?? 0) }] }, })) }, } `, }) + expect(result.isError).toBe(false) - expect(result.isError).toBe(true) - expect(text(result)).toContain('harness.defineTool parameters use the SchemaSpec DSL') - expect(ctx.tools.get('bad_json_schema_tool')).toBeUndefined() + // The registered schema is canonical JSON Schema derived from the DSL: + // the required array survived, integer became number, extra is optional. + const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')! + const parameters = schema.parameters as { properties: Record; required?: string[] } + expect(parameters.required).toEqual(['text']) + expect(parameters.properties.count!.type).toBe('number') + expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow']) + // Arg validation enforces the normalized spec: text required, extra not. + expect((await call(ctx, 'json_schema_tool', { count: 2 })).isError).toBe(true) + expect(text(await call(ctx, 'json_schema_tool', { text: 'ok', count: 2 }))).toBe('ok:2') + }) + + it('normalizes a nested object property carrying a JSON-Schema required array', async () => { + // On an object PROPERTY, a JSON-Schema-style `required` array names the + // required children — the nested unwrap converts it just like the top level. + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'nested-json-schema', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'nested_json_schema_tool', + description: 'nested dialect', + parameters: { + cfg: { type: 'object', properties: { label: { type: 'string' } }, required: ['label'] }, + }, + async execute(args) { return [{ type: 'text', text: args.cfg.label }] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(false) + const schema = ctx.tools.schemas().find(s => s.name === 'nested_json_schema_tool')! + const cfg = (schema.parameters as { properties: { cfg: { required?: string[] } } }).properties.cfg + expect(cfg.required).toEqual(['label']) + expect(text(await call(ctx, 'nested_json_schema_tool', { cfg: { label: 'hi' } }))).toBe('hi') }) it.each([ ['parameters: 42', 'must be a SchemaSpec object'], ['parameters: { text: 42 }', 'parameters.text must be a SchemaSpec property object'], - ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type'], - ['parameters: { text: { type: \'string\', required: false } }', 'parameters.text.required must be true when present'], + ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type: \'string\' | \'number\' | \'boolean\' | \'object\' | \'array\' (got "str")'], + ['parameters: { text: { type: \'string\', required: \'yes\' } }', 'parameters.text.required must be a boolean when present'], ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is only valid for type "object"'], ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is only valid for type "array"'], ])('rejects a malformed SchemaSpec (%s) with a teaching error', async (parameters, message) => { From ea66641b84c170d0b133ee66ab6c7cc955b12cf8 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 21:01:49 +0800 Subject: [PATCH 086/119] feat(tool-cordis): flatten the inspect plugins section to a capability list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tree SHAPE was the wrong surface for the model: what it needs from cordis_inspect is what services, plugins, and capabilities are loaded, not the fiber hierarchy. The plugins section is now a flat name + lifecycle-state list from ctx.registry (deterministically sorted, one line per instance); the ASCII tree renderer, the parent→child rebuild, and the dyn-id tree annotation are deleted — dynamic mounts keep their own richer dynamic section (id, state, provides, waits). Net -49 lines; RFC and READMEs state the flat-list contract. --- ...6-07-08-self-referential-cordis-toolset.md | 8 +-- docs/tool-catalog.md | 2 +- packages/cordis/README.md | 2 +- packages/cordis/tool-cordis/README.md | 2 +- .../cordis/tool-cordis/src/fiber-state.ts | 2 +- packages/cordis/tool-cordis/src/index.ts | 25 +++----- packages/cordis/tool-cordis/src/inspect.ts | 60 ++++--------------- .../cordis/tool-cordis/tests/inspect.spec.ts | 42 ++++++------- 8 files changed, 47 insertions(+), 96 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 14e05b0afd..26daf4a844 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -22,11 +22,11 @@ The trust stance, stated once and threaded through the rest: the `node:vm` sandb | `cordis_mount` | Evaluates `code` (the body of an async JavaScript function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted as a child of the `cordis-dynamic` group fiber and tracked under a fresh id (`dyn-1`, `dyn-2`, …). | | `cordis_unmount` | Disposes one dynamic mount by id and returns only after disposal reaches quiescence — every registration the plugin made is unwound, not merely requested to stop. | -`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (the whole plugin fiber tree rebuilt from `ctx.registry`, ASCII, dynamic mounts annotated with their ids), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering. +`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (a flat list of every loaded plugin with its lifecycle state, from `ctx.registry` — what capabilities are loaded, deliberately not the tree shape), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering. ### Sandbox semantics -Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through the fiber tree and disposable with it. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). +Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through `cordis_inspect` and disposable with its fiber. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. @@ -36,7 +36,7 @@ Boundary errors are written around the mistakes models actually make (see [Conse ### The dynamic group and mount lifecycle -Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself a child of the `tool-cordis` plugin's fiber. The group exists so the mounts form one subtree: they read as a unit in the inspect tree, and disposing `tool-cordis` (HMR reload, config unload) cascades over every mount through the ordinary parent→child fiber lifecycle — no bespoke cleanup. Mounting settles before it reports: the returned fiber is `await()`ed, and a startup error (a throwing `apply`, a duplicate tool name, a duplicate service) disposes the fiber and surfaces as the tool error, so a failed mount never lingers. A settled fiber that is not active is a legal pending mount — cordis semantics for unsatisfied `inject` — kept mounted and reported with what it waits for. Everything the plugin registers is an effect on its fiber, so `cordis_unmount` is nothing but an awaited `fiber.dispose()`. +Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself a child of the `tool-cordis` plugin's fiber. The group exists so the mounts form one subtree: they are disposed as a unit, and disposing `tool-cordis` (HMR reload, config unload) cascades over every mount through the ordinary parent→child fiber lifecycle — no bespoke cleanup. Mounting settles before it reports: the returned fiber is `await()`ed, and a startup error (a throwing `apply`, a duplicate tool name, a duplicate service) disposes the fiber and surfaces as the tool error, so a failed mount never lingers. A settled fiber that is not active is a legal pending mount — cordis semantics for unsatisfied `inject` — kept mounted and reported with what it waits for. Everything the plugin registers is an effect on its fiber, so `cordis_unmount` is nothing but an awaited `fiber.dispose()`. ### Cross-mount composition via provide/inject @@ -64,7 +64,7 @@ Model-visible ⟺ logged holds with no new session event type: a mount or unmoun | The code field | An `execute` body is still model-written JS in a vm; the realm and service-call correctness problems are unchanged | One sandbox, one normalization path, one guarded registration | | Capability coverage | Tools only; listeners, services, `inject` relations each need another structured tool — a surface that grows without bound | One vocabulary (a cordis plugin) covers every effect, present and future | | Cross-mount composition | Not expressible in a tool-registration payload | Native `provide`/`inject`, ordinary cordis semantics | -| Inspectability | Registers something the plugin tree cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders | +| Inspectability | Registers something the plugin list cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders | | Model ergonomics | Wins for the single most common case (no plugin boilerplate) | Mitigated by the canonical recipe in the mount description plus boundary errors that teach the fix | The correctness investment therefore goes where it pays for every capability at once: the generated API catalog surfaced through `cordis_inspect`, and sandbox-boundary validation whose error messages teach the correct call. A structured registration tool remains addable later as sugar that synthesizes mount code; nothing here forecloses it. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 91c2104a13..ec1546592c 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -110,7 +110,7 @@ The bash/bash_output/bash_kill tools are model-facing consumers of the bash exec ### `cordis_inspect` -Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — dynamic mounts appear under the `cordis-dynamic` group with their ids), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. +Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. ```json { diff --git a/packages/cordis/README.md b/packages/cordis/README.md index 2eb33006e5..70c7e41ce0 100644 --- a/packages/cordis/README.md +++ b/packages/cordis/README.md @@ -1,6 +1,6 @@ # packages/cordis — the self-referential runtime toolset -Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the plugin tree and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). +Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). | Package | Role | ctx key | |---|---|---| diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md index 71b79fecad..b369a7209b 100644 --- a/packages/cordis/tool-cordis/README.md +++ b/packages/cordis/tool-cordis/README.md @@ -4,7 +4,7 @@ The self-referential cordis toolset: three model-facing tools over the live runt ## What it does -- `cordis_inspect` — read-only report over the runtime: services, the plugin fiber tree (ASCII), registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. +- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. - `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-`. - `cordis_unmount` — disposes one mount by id, returning only after quiescence. diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/cordis/tool-cordis/src/fiber-state.ts index e46700c387..2b1ee166b7 100644 --- a/packages/cordis/tool-cordis/src/fiber-state.ts +++ b/packages/cordis/tool-cordis/src/fiber-state.ts @@ -1,7 +1,7 @@ /** * Runtime mirror of the cordis `FiberState` const enum plus human-readable * labels, shared by the mount lifecycle (state reporting) and the inspect - * renderers (tree and mount-table labels). + * renderers (plugin-list and mount-table labels). * * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for * Node's type-stripping runner to import, so the members are mirrored here as diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index 7dff9b993d..875637bfc4 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -2,8 +2,8 @@ * The self-referential cordis toolset: three model-facing tools that let the * agent inspect and MODIFY the live cordis runtime it is running inside. * - * - `cordis_inspect` — read-only: provided services, the plugin fiber tree - * (rendered as an ASCII tree), registered tools, the dynamic mounts, and the + * - `cordis_inspect` — read-only: provided services, the flat plugin list + * with lifecycle states, registered tools, the dynamic mounts, and the * catalog-backed `api` / `events` references. * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the * code returns a cordis plugin, which is mounted as a child of a dedicated @@ -14,8 +14,8 @@ * `harness.registerTool`, services via `ctx.provide`) is an effect on the * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans * it all up through the ordinary cordis lifecycle. The group fiber exists - * exactly so the dynamic mounts form ONE subtree: visible as a unit in the - * inspect tree and disposed as a unit with this plugin. Design home: + * exactly so the dynamic mounts form ONE subtree, disposed as a unit with + * this plugin. Design home: * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. * * The vm sandbox guards against ACCIDENTAL global pollution only — it is not a @@ -31,12 +31,12 @@ * @module @deepseek-ai/dsh-tool-cordis */ -import type { Context, Fiber } from 'cordis' +import type { Context } from 'cordis' import z from 'schemastery' import { defineTool } from '@deepseek-ai/dsh-tools' import { STATE_LABELS } from './fiber-state.ts' import { isPlugin, pluginName } from './guard.ts' -import { describeApi, describeDynamic, describeEvents, describePluginTree, describeServices, describeTools } from './inspect.ts' +import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts' import { missingServices, mountDynamic } from './mount.ts' import type { DynamicMount } from './mount.ts' import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts' @@ -79,21 +79,12 @@ export function apply(ctx: Context, config: Config): void { const mounts = new Map() let nextId = 1 - /** The dynamic-mount id for a fiber, when that fiber is a tracked mount. */ - function mountIdOf(fiber: Fiber): string | undefined { - for (const [id, mount] of mounts) { - if (mount.fiber === fiber) return id - } - return undefined - } - ctx.tools.register(defineTool({ name: 'cordis_inspect', description: 'Inspect the live cordis runtime that is running THIS agent. Read-only. ' + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), ' - + '`plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — ' - + 'dynamic mounts appear under the `cordis-dynamic` group with their ids), ' + + '`plugins` (a flat list of the loaded plugins with their lifecycle states), ' + '`tools` (the model-facing tools currently registered, i.e. what you can call), ' + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), ' + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), ' @@ -109,7 +100,7 @@ export function apply(ctx: Context, config: Config): void { execute(args): Promise<{ type: 'text'; text: string }[]> { const sections: [heading: string, body: () => string[]][] = [ ['services', () => describeServices(ctx)], - ['plugins', () => describePluginTree(ctx, mountIdOf)], + ['plugins', () => describePlugins(ctx)], ['tools', () => describeTools(ctx)], ['dynamic', () => describeDynamic(ctx, mounts)], ['api', () => describeApi(ctx)], diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/cordis/tool-cordis/src/inspect.ts index dfcc9a0c6b..5b44ed7ca5 100644 --- a/packages/cordis/tool-cordis/src/inspect.ts +++ b/packages/cordis/tool-cordis/src/inspect.ts @@ -1,6 +1,6 @@ /** * Read-only renderers over the live runtime for `cordis_inspect`: the service - * list, the plugin fiber tree (ASCII), the registered tools, the dynamic-mount + * list, the flat plugin list, the registered tools, the dynamic-mount * table (with per-mount provides/waits), and the catalog-backed `api` / * `events` sections. Every renderer is a pure function of the runtime handles * it receives — no session state, no clock — so inspect output is exactly the @@ -57,56 +57,22 @@ export function describeServices(ctx: Context): string[] { return lines.length > 0 ? lines : ['(no services provided)'] } -/** The tree node shape {@link renderTree} draws: one line per fiber, children indented. */ -interface TreeNode { - label: string - children: TreeNode[] -} - -/** Render a node list as an ASCII tree (`├─`/`└─` box drawing). */ -function renderTree(nodes: TreeNode[], prefix = ''): string[] { - return nodes.flatMap((node, index) => { - const last = index === nodes.length - 1 - const line = `${prefix}${last ? '└─' : '├─'} ${node.label}` - const childPrefix = `${prefix}${last ? ' ' : '│ '}` - return [line, ...renderTree(node.children, childPrefix)] - }) -} - /** - * The `plugins` section: every fiber the registry knows, rebuilt into the - * parent→child tree from each fiber's mounting context and rendered as an - * ASCII tree with lifecycle states. Fibers whose parent fiber is outside the - * registry (i.e. mounted on the root context) become roots. - * @param ctx - the runtime whose registry is walked. - * @param mountIdOf - resolves a fiber to its dynamic-mount id, so mounts render as `dyn-: name`. - * @returns the tree lines, starting at the synthetic `root` line. + * The `plugins` section: a flat list of every fiber the registry knows, one + * line per fiber with its lifecycle state, sorted by plugin name (a plugin + * mounted more than once repeats — one line per instance). Dynamic mounts are + * listed like any other plugin; their ids live in the `dynamic` section. + * @param ctx - the runtime whose registry is enumerated. + * @returns one line per loaded plugin fiber. */ -export function describePluginTree(ctx: Context, mountIdOf: (fiber: Fiber) => string | undefined): string[] { - const fibers = new Set() +export function describePlugins(ctx: Context): string[] { + const fibers: Fiber[] = [] for (const runtime of ctx.registry.values()) { - for (const fiber of runtime.fibers) fibers.add(fiber) + for (const fiber of runtime.fibers) fibers.push(fiber) } - const childrenOf = new Map() - const roots: Fiber[] = [] - for (const fiber of fibers) { - const parent = fiber.parent.fiber - if (fibers.has(parent)) { - const siblings = childrenOf.get(parent) ?? [] - siblings.push(fiber) - childrenOf.set(parent, siblings) - } else { - roots.push(fiber) - } - } - const byUid = (a: Fiber, b: Fiber): number => (a.uid ?? Infinity) - (b.uid ?? Infinity) - const toNode = (fiber: Fiber): TreeNode => { - const id = mountIdOf(fiber) - const label = `${id ? `${id}: ` : ''}${fiber.name} [${STATE_LABELS[fiber.state]}]` - const children = (childrenOf.get(fiber) ?? []).sort(byUid).map(toNode) - return { label, children } - } - return ['root', ...renderTree(roots.sort(byUid).map(toNode))] + return fibers + .sort((a, b) => a.name.localeCompare(b.name)) + .map(fiber => `- ${fiber.name} [${STATE_LABELS[fiber.state]}]`) } /** diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/cordis/tool-cordis/tests/inspect.spec.ts index c45d3b29a8..1a8c39467a 100644 --- a/packages/cordis/tool-cordis/tests/inspect.spec.ts +++ b/packages/cordis/tool-cordis/tests/inspect.spec.ts @@ -1,13 +1,13 @@ import { describe, expect, it } from 'vitest' import type { Context, Fiber } from 'cordis' import { FiberState } from '../src/fiber-state.ts' -import { describeApi, describeEvents, describePluginTree, describeServices } from '../src/inspect.ts' +import { describeApi, describeEvents, describePlugins, describeServices } from '../src/inspect.ts' import { call, LISTENER_CODE, setup, text } from './helpers.ts' /** * The `cordis_inspect` sections: rendered against the real runtime through the * tool, plus direct renderer calls for the states a minimal harness cannot - * reach (empty service store, uid-less fibers, a fully-live catalog). + * reach (empty service store, same-named sibling fibers, a fully-live catalog). */ describe('cordis_inspect', () => { @@ -19,11 +19,12 @@ describe('cordis_inspect', () => { for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) { expect(report).toContain(`## ${heading}`) } - // The services section sees the real providers; the tree shows the dynamic - // group under this plugin; the tools section lists the cordis tools. + // The services section sees the real providers; the plugins list shows + // this plugin and its dynamic group flat; the tools section lists the + // cordis tools. expect(report).toContain('- tools (provided by ToolRegistry)') - expect(report).toMatch(/tool-cordis \[active\]/) - expect(report).toMatch(/cordis-dynamic \[active\]/) + expect(report).toContain('- tool-cordis [active]') + expect(report).toContain('- cordis-dynamic [active]') expect(report).toContain('- cordis_mount') expect(report).toContain('(no dynamic plugins mounted)') }) @@ -37,12 +38,12 @@ describe('cordis_inspect', () => { expect(report).not.toContain('## plugins') }) - it('shows a mount in the dynamic section and as an annotated child of the group in the tree', async () => { + it('shows a mount in the dynamic section and in the flat plugins list', async () => { const ctx = await setup() await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) const report = text(await call(ctx, 'cordis_inspect', {})) expect(report).toContain('- dyn-1: change-logger [active]') - expect(report).toMatch(/dyn-1: change-logger \[active\]/) + expect(report).toContain('- change-logger [active]') }) it('renders the api section from the generated catalog intersected with the LIVE runtime', async () => { @@ -87,22 +88,15 @@ describe('inspect renderers (direct)', () => { expect(describeServices(ctx)).toEqual(['- thing (provided by half-loaded, pending)']) }) - it('describePluginTree sorts uid-less fibers last and renders sibling branches', () => { - // The parent fiber is OUTSIDE the registry set, so all three are roots. - const rootFiber = { uid: 0, name: 'root' } as unknown as Fiber - const fiber = (uid: number | null, name: string): Fiber => - ({ uid, name, state: FiberState.ACTIVE, parent: { fiber: rootFiber } }) as unknown as Fiber - const a = fiber(2, 'beta') - const b = fiber(1, 'alpha') - const c = fiber(null, 'rootless') - const d = fiber(null, 'rootless-too') - const ctx = { registry: { values: () => [{ fibers: [a, b, c, d] }] } } as unknown as Context - expect(describePluginTree(ctx, () => undefined)).toEqual([ - 'root', - '├─ alpha [active]', - '├─ beta [active]', - '├─ rootless [active]', - '└─ rootless-too [active]', + it('describePlugins lists every fiber flat, sorted by name, one line per instance', () => { + const fiber = (name: string): Fiber => ({ name, state: FiberState.ACTIVE }) as unknown as Fiber + const ctx = { + registry: { values: () => [{ fibers: [fiber('beta'), fiber('alpha')] }, { fibers: [fiber('alpha')] }] }, + } as unknown as Context + expect(describePlugins(ctx)).toEqual([ + '- alpha [active]', + '- alpha [active]', + '- beta [active]', ]) }) From aed752a75da17e0b89263cbbb5c8b362d12785a0 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 21:30:17 +0800 Subject: [PATCH 087/119] fix: update doc budget --- scripts/doc-budgets.manifest.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 8cadde12e9..49535f0efb 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -7,5 +7,5 @@ "docs/testing.md": 800, "examples/AGENTS.md": 653, "packages/AGENTS.md": 450, - "packages/README.md": 610 + "packages/README.md": 660 } From 1b1ba96d4f608d7ea3bd9ea74d5b5ea1c169b14b Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 01:37:40 +0800 Subject: [PATCH 088/119] =?UTF-8?q?fix(tool-cordis):=20replace=20the=20pas?= =?UTF-8?q?s-through=20ctx=20proxy=20with=20a=20whitelist=20fa=C3=A7ade?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding (#220): the guarded proxy only special-cased ctx.tools, so mount code could reach an UNGUARDED context through ctx.root, ctx.extend(), or a service instance's .ctx, then ctx.root.tools.register({…}) to bypass the marker check and host-realm normalization — a raw vm-realm result would later error a real agent turn at the session-log plainness check. The sandbox ctx is now a whitelist façade, not a pass-through proxy: it exposes only what a mount needs — tools.register (marker-guarded), on/once, provide, the timer helpers, and injected services resolved through a guarded get — and denies every framework-plumbing member (root, parent, fiber, reflect, registry, extend, isolate, intercept, plugin, set, mixin, …) with a teaching error. Injected services are wrapped so a method returning a Context is rejected on the way back (the .ctx escape), closing the one indirect leak. There is no context-valued member left to reach; cross-mount provide/inject is untouched (the plugin's own inject and the fiber's pending/active gating are unchanged). ctx.plugin (child plugins) and ctx.set are denied by design; ctx.effect is deferred (FIXME). Adds tests/sandbox-context.spec.ts covering the escape class (root/extend/fiber/ plugin/set/… denied, the classic root.tools.register bypass, the .ctx escape, read-only writes) plus the async-service and symbol/in-operator paths for 100% coverage. RFC/README/tool-catalog/config-catalog updated; api-catalog.ts regenerated (also picks up the codeRuntime service that entered on the master merge and was left stale). --- docs/config-catalog.md | 2 +- ...6-07-08-self-referential-cordis-toolset.md | 8 +- docs/tool-catalog.md | 2 +- packages/cordis/tool-cordis/README.md | 2 +- .../cordis/tool-cordis/src/api-catalog.ts | 31 ++++ packages/cordis/tool-cordis/src/guard.ts | 169 ++++++++++++++---- packages/cordis/tool-cordis/src/index.ts | 19 +- .../cordis/tool-cordis/tests/mount.spec.ts | 4 +- .../tool-cordis/tests/sandbox-context.spec.ts | 156 ++++++++++++++++ 9 files changed, 348 insertions(+), 45 deletions(-) create mode 100644 packages/cordis/tool-cordis/tests/sandbox-context.spec.ts diff --git a/docs/config-catalog.md b/docs/config-catalog.md index d466bff4c0..2e6be3a1ea 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -686,7 +686,7 @@ export interface Config { } ``` -Source: [`packages/cordis/tool-cordis/src/index.ts:49`](../packages/cordis/tool-cordis/src/index.ts) +Source: [`packages/cordis/tool-cordis/src/index.ts:53`](../packages/cordis/tool-cordis/src/index.ts) ## `@deepseek-ai/dsh-tool-fs` diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 26daf4a844..2ba398301b 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -12,7 +12,7 @@ First, model-written registration must be validated where it happens: a malforme The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) — a new top-level `packages/cordis/` group — and is demoed by [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md). It gives the model three tools over the live cordis runtime it is running inside: inspect it, mount model-written plugins into it, dispose them again. -The trust stance, stated once and threaded through the rest: the `node:vm` sandbox isolates the global context only — it prevents accidental global pollution, not malice. The `ctx` handed to a mounted plugin's `apply` is the real, fully privileged runtime handle; handing the model that handle is the point of the toolset. A deployment loads this plugin exactly as deliberately as it grants a bash tool — an opt-in capability in the app's `cordis.yml`, never a product default. +The trust stance, stated once and threaded through the rest: the `node:vm` sandbox isolates the global context only — it prevents accidental global pollution, not malice — and the `ctx` a mounted plugin's `apply` receives is a whitelist façade that narrows the *surface* (framework internals withheld) but not the *privilege* of what it exposes. The verbs the façade does expose reach the real runtime: a mounted tool can shell out through `ctx.bash`, read the filesystem through `ctx.fs`, reach the network through `ctx.web`. Neither the sandbox nor the façade is a security boundary; handing the model this power is the point of the toolset. A deployment loads this plugin exactly as deliberately as it grants a bash tool — an opt-in capability in the app's `cordis.yml`, never a product default. ### The three tools @@ -30,7 +30,7 @@ Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. -Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **Guarded registration**: the `ctx` a mounted plugin receives is a proxy whose `tools.register` accepts only definitions returned by `harness.defineTool` (a marker symbol), so every dynamic tool passes SchemaSpec validation and realm normalization; everything else on `ctx` passes through with correct `this` binding, which is what keeps cross-mount `provide`/`inject` working. +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, `on`/`once`, `provide`, the timer helpers, and injected services resolved through a guarded `get`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code; cross-mount `provide`/`inject` keeps working because the plugin's own `inject` and the fiber's pending/active gating are untouched — only the `apply`-time `ctx` surface is narrowed. Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. @@ -40,7 +40,7 @@ Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself ### Cross-mount composition via provide/inject -Mounts relate to each other through ordinary cordis service semantics, with their ids as the lifecycle handles: mount A calls `ctx.provide('foo', value)`, mount B declares `inject: ['foo']` and activates the moment `foo` exists; mounted first, B stays pending and names the missing service; unmounting A sends B back to pending (its registrations unwound) and a later re-provide re-runs B's `apply` through the same guarded context; a duplicate provide fails loud with the owning fiber named. One realm caveat: a service value provided by a mount is a vm-realm object — method calls on it work from anywhere, but consumers must not assume host prototypes on it. +Mounts relate to each other through ordinary cordis service semantics, with their ids as the lifecycle handles: mount A calls `ctx.provide('foo', value)`, mount B declares `inject: ['foo']` and activates the moment `foo` exists; mounted first, B stays pending and names the missing service; unmounting A sends B back to pending (its registrations unwound) and a later re-provide re-runs B's `apply` through a fresh sandbox façade; a duplicate provide fails loud with the owning fiber named. One realm caveat: a service value provided by a mount is a vm-realm object — method calls on it work from anywhere, but consumers must not assume host prototypes on it. ### The generated API catalog @@ -73,7 +73,7 @@ The correctness investment therefore goes where it pays for every capability at **A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a request-header delta, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call. -**A hardened / capability-restricted sandbox.** Trapping Node built-ins might suggest an intent to sandbox for safety. It is explicitly not that: the traps redirect the model toward cordis services (and away from leak-prone Node timers) for correctness and inspectability, but `ctx` is fully privileged and the vm is not a security boundary. A real security boundary (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. +**A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *surface* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. ## Consequences diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index ec1546592c..990e135b1c 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. ```json { diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md index b369a7209b..651f3273d9 100644 --- a/packages/cordis/tool-cordis/README.md +++ b/packages/cordis/tool-cordis/README.md @@ -12,7 +12,7 @@ Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-cata ## Trust stance -The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is the real, fully privileged runtime handle; load this plugin as deliberately as you would grant a bash tool. +The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool. ## Config diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 39f1a12f47..83170d8dc1 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -88,6 +88,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'onTaskDone(listener: BashTaskListener): () => void', ], }, + { + key: 'codeRuntime', + summary: 'Abstract code-execution service.', + methods: [ + 'abstract run(request: CodeRunRequest): Promise', + ], + }, { key: 'compact', summary: 'Abstract compaction service.', @@ -429,6 +436,30 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'CallId', declaration: 'export type CallId = Branded<\'CallId\'>;', }, + { + name: 'CodeBindingFunction', + declaration: 'export type CodeBindingFunction = (args: unknown) => Promise;', + }, + { + name: 'CodeBindingNamespace', + declaration: 'export interface CodeBindingNamespace {\n global: string;\n functions: Record;\n}', + }, + { + name: 'CodeLogEntry', + declaration: 'export interface CodeLogEntry {\n source: \'console\' | \'stdout\' | \'stderr\';\n level?: \'log\' | \'info\' | \'warn\' | \'error\' | \'debug\';\n text: string;\n}', + }, + { + name: 'CodeRunFailure', + declaration: 'export interface CodeRunFailure {\n kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\';\n message: string;\n}', + }, + { + name: 'CodeRunRequest', + declaration: 'export interface CodeRunRequest {\n program: string;\n bindings: CodeBindingNamespace[];\n signal?: AbortSignal;\n}', + }, + { + name: 'CodeRunResult', + declaration: 'export interface CodeRunResult {\n value?: unknown;\n logs: CodeLogEntry[];\n error?: CodeRunFailure;\n}', + }, { name: 'CollectedOutput', declaration: 'export interface CollectedOutput {\n text: string;\n truncated: boolean;\n spillPath?: string;\n}', diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 998997a8f9..07cd0f1df3 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -2,18 +2,35 @@ * The registration boundary between sandboxed mount code and the real runtime: * SchemaSpec normalization + validation with teaching errors, the * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the - * guarded `ctx` proxy a mounted plugin receives, and the plugin-shape helpers - * the mount lifecycle narrows sandbox return values with. + * SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives in place of the + * real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox + * return values with. * - * Two realm facts drive the design. Objects built inside the vm carry the vm + * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do + * exactly four things — register a tool, listen to an event, provide a service, + * call an injected service (timers included) — so the façade exposes only those + * verbs and the injected services, each individually wrapped. Every framework + * plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`, + * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is + * DENIED with a teaching error rather than passed through. This closes an + * entire escape class at once: a pass-through proxy that only special-cased + * `ctx.tools` still handed back the raw context through `ctx.root`, + * `ctx.extend()`, or a service instance's `.ctx`, and mount code could then + * `ctx.root.tools.register({…})` to bypass the marker check and host-realm + * normalization — a raw vm-realm result then errors a real agent turn at the + * session-log plainness check. The whitelist has no such hole: there is no + * context-valued member to reach, and any injected-service method that returns + * a `Context` is rejected (harness services never do — see {@link denyContext}). + * + * Two realm facts drive the tool path. Objects built inside the vm carry the vm * realm's `Object.prototype`, and the session log's append-time plainness check * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects * foreign-realm data — so every dynamic tool's `execute` return is JSON * round-tripped into the host realm before it reaches the registry, and the * schema itself is rebuilt as fresh host-realm objects. And a malformed tool * schema must fail at REGISTRATION, not when a later request assembles it — so - * dynamic `ctx.tools.register` calls accept only definitions produced by the - * sandbox's `harness.defineTool`, which normalizes `parameters` up front. + * dynamic tool registration accepts only definitions produced by the sandbox's + * `harness.defineTool`, which normalizes `parameters` up front. * * Normalize, don't lecture, where the input has exactly one meaning: models * write the JSON-Schema dialect by strong prior (the `{ type: 'object', @@ -26,7 +43,8 @@ * @module @deepseek-ai/dsh-tool-cordis/guard */ -import type { Context, Plugin } from 'cordis' +import { Context } from 'cordis' +import type { Plugin } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools' @@ -153,31 +171,116 @@ export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void { return ctx.tools.register(tool) } -function bindMethod(value: unknown, target: object): unknown { - if (typeof value !== 'function') return value - return (...args: unknown[]): unknown => Reflect.apply(value, target, args) as unknown +/** + * The verbs a mounted plugin may reach through the sandbox `ctx` façade, + * beyond its injected services. `on`/`once` observe events, `provide` exposes + * a service to other mounts, and the timer helpers schedule work — each a + * fiber effect that unwinds on unmount. Everything else on a real cordis `ctx` + * is framework plumbing and is denied. Forwarded LAZILY: the timer helpers are + * mixin accessors that throw `without inject` when read on a plugin that did + * not inject `timer`, so the façade reads `ctx[verb]` only at call time — the + * plugin that never touches a timer never trips that, and one that does gets + * cordis's own inject error at the call site. + */ +const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce']) + +/** + * The tool-registry façade: only `register` (marker-guarded), plus the + * read-only `schemas` / `get` a mount may legitimately want. No other registry + * method (nothing that could re-enter the raw context) is exposed. + */ +function sandboxTools(ctx: Context): Record { + return { + register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool), + schemas: () => ctx.tools.schemas(), + get: (name: string) => ctx.tools.get(name), + } } -function guardedContext(ctx: Context): Context { - const tools = new Proxy(ctx.tools, { +/** + * Reject any injected-service return that is a cordis `Context`. Harness + * services return data, never a context; a value that is one would be a + * fresh, unguarded handle back into the runtime — the exact escape the façade + * exists to close — so it fails loud instead of reaching sandbox code. + */ +function denyContext(value: unknown, service: string): unknown { + if (value instanceof Context) { + throw new Error( + `service "${service}" returned a cordis Context, which the sandbox does not expose. ` + + 'Operate through your own plugin ctx (ctx.on / ctx.provide / ctx.tools.register) ' + + 'and the services you inject — never another context.', + ) + } + return value +} + +/** + * Wrap an injected service so its methods forward to the real instance but + * their return values pass through {@link denyContext}. Non-function members + * (plain data) pass through as-is; a returned Promise is guarded on resolve. + */ +function guardedService(service: object, name: string): unknown { + return new Proxy(service, { get(target, prop) { - if (prop === 'register') { - return (tool: unknown): () => void => sandboxRegisterTool(ctx, tool) - } const value = Reflect.get(target, prop, target) as unknown - return bindMethod(value, target) + if (typeof value !== 'function') return denyContext(value, name) + return (...args: unknown[]): unknown => { + const result = Reflect.apply(value, target, args) as unknown + if (result instanceof Promise) return result.then(v => denyContext(v, name)) + return denyContext(result, name) + } }, }) - return new Proxy(ctx, { - get(target, prop) { +} + +/** + * The sandbox context façade handed to a mounted plugin's `apply` in place of + * the real `ctx`. A whitelist (see the module doc): the registration/eventing + * verbs, the timer helpers, a guarded `tools`, and injected services resolved + * through a guarded `get` / property access. Every framework-plumbing member + * is denied with a teaching error; there is no context-valued member to reach. + */ +function sandboxContext(ctx: Context): Context { + const tools = sandboxTools(ctx) + // Resolve a named service to a guarded wrapper, or undefined when absent. + const resolveService = (name: string): unknown => { + if (name === 'tools') return tools + const service: unknown = ctx.get(name) + return service === undefined ? undefined : guardedService(service as object, name) + } + const get = (name: string): unknown => resolveService(name) + return new Proxy({}, { + get(_target, prop) { if (prop === 'tools') return tools - if (prop === 'get') { - return (service: string): unknown => service === 'tools' ? tools : target.get(service) + if (prop === 'get') return get + if (typeof prop !== 'string') return undefined + // Lazy verb forwarder — reads `ctx[verb]` only when called, so a plugin + // that never uses a timer never triggers the timer mixin's inject check. + if (CTX_VERBS.has(prop)) { + return (...args: unknown[]): unknown => { + const method = ctx[prop as keyof Context] + return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args) + } } - const value = Reflect.get(target, prop, target) as unknown - return bindMethod(value, target) + // A declared-and-injected service reads as a ctx property; resolve it + // through the same guard. Absent → the deny path (framework plumbing, + // an un-injected service, or a typo) with one teaching error. + const service = resolveService(prop) + if (service !== undefined) return service + throw new Error( + `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / ` + + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. ' + + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.', + ) }, - }) + // A façade is not the real ctx; block writes rather than let mount code + // stash state on a throwaway object and think it persisted. + set(_target, prop) { + throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`) + }, + has: (_target, prop) => prop === 'tools' || prop === 'get' + || (typeof prop === 'string' && (CTX_VERBS.has(prop) || resolveService(prop) !== undefined)), + }) as unknown as Context } /** @@ -194,13 +297,19 @@ export function isPlugin(value: unknown): value is Plugin { } /** - * Wrap a plugin so its `apply` receives a guarded context (`tools.register` - * only accepts tools from `harness.defineTool`). Both function-form and - * object-form plugins go through the same guard; everything else on the - * context — `on`, `provide`, `inject` resolution — passes through with correct - * `this` binding, so cross-mount provide/inject works unmodified. + * Wrap a plugin so its `apply` receives the sandbox context façade instead of + * the real `ctx` (see {@link sandboxContext} and the module doc). Both + * function-form and object-form plugins go through the same wrap; the plugin's + * own `inject` declaration is preserved (cordis reads it from the plugin + * object, and pending/active gating happens on the real fiber before `apply` + * runs), so cross-mount provide/inject works unmodified. + * + * `ctx.effect(customCleanup)` is deliberately absent from the façade for now — + * `on` / `provide` / `tools.register` cover every mount seen so far, and each + * is already a fiber effect. FIXME(sandbox-effect): expose a guarded `effect` + * once a real mount needs a bespoke disposer. * @param plugin - the plugin the mount code returned. - * @returns an equivalent plugin whose `apply` sees the guarded context. + * @returns an equivalent plugin whose `apply` sees the sandbox context façade. */ export function guardedPlugin(plugin: Plugin): Plugin { if (typeof plugin === 'function') { @@ -208,7 +317,7 @@ export function guardedPlugin(plugin: Plugin): Plugin { return { name: pluginName(plugin), apply(ctx: Context, config?: unknown) { - return functionPlugin(guardedContext(ctx), config) + return functionPlugin(sandboxContext(ctx), config) }, } } @@ -216,7 +325,7 @@ export function guardedPlugin(plugin: Plugin): Plugin { return { ...plugin, apply(ctx: Context, config?: unknown) { - return objectPlugin.apply(guardedContext(ctx), config) + return objectPlugin.apply(sandboxContext(ctx), config) }, } } diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index 875637bfc4..f7d1958625 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -18,10 +18,14 @@ * this plugin. Design home: * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. * - * The vm sandbox guards against ACCIDENTAL global pollution only — it is not a - * security boundary. The `ctx` handed to the mounted plugin's `apply` is the - * real, fully privileged runtime handle; that is the point of the toolset, so - * a deployment loads this plugin as deliberately as it grants a bash tool. + * The vm sandbox guards against ACCIDENTAL global pollution only, and the `ctx` + * a mounted plugin's `apply` receives is a WHITELIST façade (register a tool, + * observe events, provide/consume services, use timers — framework internals + * withheld; see the guard module). Neither is a security boundary: the verbs + * the façade DOES expose reach the real runtime unsandboxed (a mounted tool can + * shell out through `ctx.bash`), so a deployment loads this plugin as + * deliberately as it grants a bash tool. Design home: + * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. * * Plugin export shape: named exports, NO default. The cordis Loader's * `unwrapExports` does `exports.default ?? exports`, so a stray default would @@ -159,8 +163,11 @@ export function apply(ctx: Context, config: Config): void { + 'VETOES the call; prefer plain notification events unless you intend to ' + 'intercept. (2) Never await something that only resolves after the current ' + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). ' - + '(3) The sandbox prevents accidental global pollution, not malice: `ctx` is ' - + 'the real, fully privileged runtime handle.', + + '(3) Your `ctx` is a restricted façade: you can register tools, observe ' + + 'events, provide/consume services, and use timers, but framework internals ' + + '(ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a ' + + 'security boundary though — the services you inject (e.g. ctx.bash) reach the ' + + 'real runtime.', parameters: { code: { type: 'string', diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 543b38307f..d0db8d7efa 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -386,13 +386,13 @@ describe('cordis_mount', () => { console.error('errored') const round = atob(btoa('hi')) const bytes = new TextEncoder().encode(round) - return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.fiber) } } + return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.on) } } `, }) expect(result.isError).toBe(false) expect(text(result)).toContain('plugin "codec-hi"') expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'warned') - expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'object') + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'function') expect(error).toHaveBeenCalledWith('[cordis:dyn-1]', 'errored') }) diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts new file mode 100644 index 0000000000..50f5b441a2 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts @@ -0,0 +1,156 @@ +import { describe, expect, it } from 'vitest' +import { call, setup, text } from './helpers.ts' + +/** + * The sandbox context façade is a whitelist, not a pass-through proxy: mount + * code reaches only the registration/eventing verbs, the timer helpers, a + * guarded `tools`, and its injected services. Every framework-plumbing member + * that could hand back an UNGUARDED context — through which a plugin could + * `ctx..tools.register({…})` to bypass the marker check and host-realm + * normalization — is denied. These are the regression guards for that escape + * class (the review finding on the original pass-through proxy). + */ + +/** Mount a plugin whose `apply` touches one framework member, and report the error text. */ +async function mountTouching(ctx: Awaited>, expr: string): Promise { + const result = await call(ctx, 'cordis_mount', { + code: `return { name: 'probe', inject: ['tools'], apply(ctx) { ${expr} } }`, + }) + expect(result.isError).toBe(true) + return text(result) +} + +describe('sandbox context façade — escape surface is closed', () => { + it.each([ + ['ctx.root', 'const c = ctx.root'], + ['ctx.parent', 'const c = ctx.parent'], + ['ctx.scope', 'const c = ctx.scope'], + ['ctx.fiber', 'const f = ctx.fiber'], + ['ctx.reflect', 'const r = ctx.reflect'], + ['ctx.registry', 'const r = ctx.registry'], + ['ctx.events', 'const e = ctx.events'], + ['ctx.extend()', 'ctx.extend({})'], + ['ctx.isolate()', 'ctx.isolate("x")'], + ['ctx.intercept()', 'ctx.intercept("x", {})'], + ['ctx.plugin()', 'ctx.plugin({ apply() {} })'], + ['ctx.set()', 'ctx.set("tools", 1)'], + ['ctx.mixin()', 'ctx.mixin("x", [])'], + ])('denies %s with a teaching error', async (_label, expr) => { + const ctx = await setup() + const message = await mountTouching(ctx, expr) + expect(message).toContain('sandbox ctx does not expose') + expect(message).toContain('withheld by design') + }) + + it('the classic ctx.root.tools.register bypass registers nothing and fails loud', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'root-bypass', + inject: ['tools'], + apply(ctx) { + ctx.root.tools.register({ + name: 'smuggled', + description: 'raw, unguarded', + parameters: { type: 'object', properties: {} }, + async execute() { return [] }, + }) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('sandbox ctx does not expose "root"') + // The whole point: the bypass never reaches the registry. + expect(ctx.tools.get('smuggled')).toBeUndefined() + }) + + it('rejects assignment to the façade rather than silently dropping it', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'writer\', apply(ctx) { ctx.stash = 1 } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('sandbox ctx is read-only') + }) + + it('denies a service whose method returns a Context (the .ctx escape), registering nothing', async () => { + // A cordis Service instance carries `.ctx` (a real Context), so + // `ctx.systemPrompt.ctx.root.tools.register(…)` would be a fresh unguarded + // handle. The service wrapper's return-value guard rejects any Context on + // the way back to sandbox code, so the escape never lands. (`systemPrompt` + // is in the setup harness, so the plugin activates and its apply runs.) + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'svc-ctx-escape', + inject: ['systemPrompt', 'tools'], + apply(ctx) { + ctx.systemPrompt.ctx.root.tools.register({ + name: 'smuggled_via_service', + description: 'raw, unguarded', + parameters: { type: 'object', properties: {} }, + async execute() { return [] }, + }) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('returned a cordis Context, which the sandbox does not expose') + expect(ctx.tools.get('smuggled_via_service')).toBeUndefined() + }) + + it('guards an async injected-service method: a host-realm Promise resolves through the guard', async () => { + // The return guard's Promise arm only fires for a HOST-realm Promise + // (a vm-realm one is not `instanceof` the host `Promise`). Provide a + // host-realm service from the test, then inject + await it from a mount: + // the resolved value is non-Context data and passes through. + const ctx = await setup() + ctx.plugin({ + name: 'host-async-svc', + apply(c) { c.provide('hostAsync', { grab: async () => 'host-fetched' }) }, + }) + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'async-consumer', + inject: ['hostAsync', 'tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'do_fetch', + description: 'awaits the host async service', + parameters: {}, + async execute() { + const value = await ctx.hostAsync.grab() + return [{ type: 'text', text: value }] + }, + })) + }, + } + `, + }) + const result = await call(ctx, 'do_fetch', {}) + expect(result.isError).toBe(false) + expect(text(result)).toBe('host-fetched') + }) + + it('reads a symbol property as undefined and answers the `in` operator without throwing', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'introspector', + inject: ['tools'], + apply(ctx) { + const sym = ctx[Symbol.iterator] + console.log('probe', sym === undefined, 'tools' in ctx, 'on' in ctx, 'root' in ctx) + }, + } + `, + }) + expect(result.isError).toBe(false) + }) +}) From 3e9527278a2e513a91c19d491170db076b91ca93 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 12:44:57 +0800 Subject: [PATCH 089/119] =?UTF-8?q?fix(tool-cordis):=20gate=20fa=C3=A7ade?= =?UTF-8?q?=20services=20on=20inject,=20and=20make=20tools.get=20read-only?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two review findings (#220) on the sandbox context façade: - Undeclared services were reachable: the façade resolved any live global via ctx.get(name), so ctx.bash worked without inject: ['bash']. A cross-mount consumer could then depend on a provider cordis never saw — unmounting the provider would neither park the consumer nor unwind its registered tools, leaving a model-visible tool that fails only at execution. The façade now reads ctx.fiber.inject and refuses any service the mount did not declare (with a teaching error naming the inject fix), so the dependency is always visible to cordis and its activation/unload semantics bind. - ctx.tools.get returned the live ToolDefinition, including execute — mount code could call another tool directly and bypass ToolRegistry.execute and its pre/post-execute hooks and accounting. get now returns the same read-only name/description/parameters view as schemas(), never an invocable. Adds inject-gate and schema-view regression cases to sandbox-context.spec.ts (undeclared property/get denied, declared allowed, the cross-mount zombie-tool scenario refused at call time, get exposes no execute). Package stays at per-file 100% coverage. RFC, mount description, and tool-catalog updated. --- ...6-07-08-self-referential-cordis-toolset.md | 2 +- docs/tool-catalog.md | 2 +- packages/cordis/tool-cordis/src/guard.ts | 84 ++++++++--- packages/cordis/tool-cordis/src/index.ts | 10 +- .../cordis/tool-cordis/tests/mount.spec.ts | 2 - .../tool-cordis/tests/sandbox-context.spec.ts | 139 ++++++++++++++++++ 6 files changed, 207 insertions(+), 32 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 2ba398301b..fff36fee91 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -30,7 +30,7 @@ Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. -Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, `on`/`once`, `provide`, the timer helpers, and injected services resolved through a guarded `get`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code; cross-mount `provide`/`inject` keeps working because the plugin's own `inject` and the fiber's pending/active gating are untouched — only the `apply`-time `ctx` surface is narrowed. +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, a read-only `tools.get`/`schemas`, `on`/`once`, `provide`, the timer helpers, and the services the plugin DECLARED in `inject`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code. Two narrower rules complete the surface. First, **service access requires an `inject` declaration**: reaching a service the mount did not declare is refused even when a global provider is live — otherwise a mount could depend on a provider cordis never sees, and unmounting that provider would neither park the consumer nor unwind the tools it registered, leaving a model-visible tool that fails only at execution time. Because the read is gated on the declaration, cross-mount `provide`/`inject` keeps its lifecycle guarantees (the plugin's own `inject` and the fiber's pending/active gating drive activation and unload); only the `apply`-time `ctx` surface is narrowed. Second, **`ctx.tools.get` returns a read-only schema view** (name/description/parameters), never the live `ToolDefinition` — handing back the definition would expose its `execute`, letting mount code call another tool directly and bypass `ToolRegistry.execute` and its pre/post-execute hooks and accounting; a mount that wants to invoke a tool must go through the registry, and one that wants to introspect gets the same view `schemas()` returns. Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 990e135b1c..a2026904cf 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. ```json { diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 07cd0f1df3..b124f6781f 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -185,15 +185,19 @@ export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void { const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce']) /** - * The tool-registry façade: only `register` (marker-guarded), plus the - * read-only `schemas` / `get` a mount may legitimately want. No other registry - * method (nothing that could re-enter the raw context) is exposed. + * The tool-registry façade: `register` (marker-guarded) plus READ-ONLY + * metadata (`schemas`, and `get` returning a schema view, never the live + * `ToolDefinition`). Exposing the raw definition would hand mount code the + * tool's `execute` function, letting it call another tool directly and bypass + * `ToolRegistry.execute` — the pre/post-execute waterfall (permission gates, + * accounting) and result normalization. So `get` returns the same + * name/description/parameters view as `schemas()`, and nothing invocable. */ function sandboxTools(ctx: Context): Record { return { register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool), schemas: () => ctx.tools.schemas(), - get: (name: string) => ctx.tools.get(name), + get: (name: string) => ctx.tools.schemas().find(schema => schema.name === name), } } @@ -233,53 +237,85 @@ function guardedService(service: object, name: string): unknown { }) } +/** + * The service names a plugin declared in `inject`, as a lookup set. Whatever + * declaration style the plugin used — an `inject: ['bash', 'tools']` array or + * the `{ required, optional }` object form — cordis resolves it into a single + * name-keyed map on the fiber before `apply` runs (`{ bash: null, tools: null }`), + * so the gate just reads that map's keys. A mount may reach only the services + * it declared — that is what lets cordis park the mount when a declared + * provider unmounts. + */ +function declaredInjects(ctx: Context): Set { + return new Set(Object.keys(ctx.fiber.inject)) +} + /** * The sandbox context façade handed to a mounted plugin's `apply` in place of * the real `ctx`. A whitelist (see the module doc): the registration/eventing * verbs, the timer helpers, a guarded `tools`, and injected services resolved - * through a guarded `get` / property access. Every framework-plumbing member - * is denied with a teaching error; there is no context-valued member to reach. + * through a guarded `get` / property access. A service is reachable only if the + * plugin DECLARED it in `inject` — an undeclared service is denied even when a + * global provider exists, so cordis's activation/unload semantics (park the + * mount when a declared provider goes away) actually bind. Every + * framework-plumbing member is denied with a teaching error; there is no + * context-valued member to reach. */ function sandboxContext(ctx: Context): Context { const tools = sandboxTools(ctx) - // Resolve a named service to a guarded wrapper, or undefined when absent. - const resolveService = (name: string): unknown => { - if (name === 'tools') return tools - const service: unknown = ctx.get(name) - return service === undefined ? undefined : guardedService(service as object, name) + const declared = declaredInjects(ctx) + // A framework member or an undeclared service — distinguish the two so the + // error teaches the right fix (declare it in inject vs it is withheld). + const denyRead = (prop: string): never => { + if (ctx.get(prop) !== undefined) { + throw new Error( + `service "${prop}" is not injected. Declare it: inject: ['${prop}', …] on your plugin, ` + + 'so cordis parks this mount if the provider is later unmounted.', + ) + } + throw new Error( + `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / ` + + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. ' + + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.', + ) } - const get = (name: string): unknown => resolveService(name) + // Read a service for either access path (property or `get`). `tools` is the + // façade's own surface. An UNDECLARED name is denied with the teaching + // error; a DECLARED one resolves to the guarded service. A declared inject + // is required in cordis (the fiber only activates once every declared + // service is live), so at `apply`/`execute` time `ctx.get(name)` is present + // for a declared name — no undefined case to handle here. + const readService = (name: string): unknown => { + if (name === 'tools') return tools + if (!declared.has(name)) return denyRead(name) + return guardedService(ctx.get(name) as object, name) + } + const get = (name: string): unknown => readService(name) return new Proxy({}, { get(_target, prop) { if (prop === 'tools') return tools if (prop === 'get') return get if (typeof prop !== 'string') return undefined // Lazy verb forwarder — reads `ctx[verb]` only when called, so a plugin - // that never uses a timer never triggers the timer mixin's inject check. + // that never uses a timer never triggers the timer mixin's inject check + // (cordis raises its own "without inject" error there for undeclared timer use). if (CTX_VERBS.has(prop)) { return (...args: unknown[]): unknown => { const method = ctx[prop as keyof Context] return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args) } } - // A declared-and-injected service reads as a ctx property; resolve it - // through the same guard. Absent → the deny path (framework plumbing, - // an un-injected service, or a typo) with one teaching error. - const service = resolveService(prop) - if (service !== undefined) return service - throw new Error( - `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / ` - + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. ' - + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.', - ) + return readService(prop) }, // A façade is not the real ctx; block writes rather than let mount code // stash state on a throwaway object and think it persisted. set(_target, prop) { throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`) }, + // `in` reflects reachability: the façade surface plus DECLARED services + // (whether or not currently live). Does not resolve/wrap — no throw. has: (_target, prop) => prop === 'tools' || prop === 'get' - || (typeof prop === 'string' && (CTX_VERBS.has(prop) || resolveService(prop) !== undefined)), + || (typeof prop === 'string' && (CTX_VERBS.has(prop) || declared.has(prop))), }) as unknown as Context } diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index f7d1958625..836d516120 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -125,12 +125,14 @@ export function apply(ctx: Context, config: Config): void { 'Mount a NEW cordis plugin into the live runtime that is running THIS agent ' + '(self-modification). `code` runs as the body of an async JavaScript function ' + 'in an isolated sandbox and MUST `return` a plugin. Two forms: ' - + 'FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever ' - + 'services are on the parent context, and accessing a service without inject ' - + '(e.g. ctx.bash) throws; use it only when you need no injected services. ' + + 'FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register ' + + 'tools, listen to events, and provide services, but reaching ANY service (e.g. ' + + 'ctx.bash) throws; use it only when you need no services. ' + 'OBJECT form `return { name?, inject: [\'bash\', \'llm\', …], apply(ctx) { … } }` ' + '— declares dependencies, and cordis activates the plugin only after the ' - + 'services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. ' + + 'services exist; PREFER this form. You may reach ONLY the services you list in ' + + 'inject: an undeclared service throws even if it exists, because an undeclared ' + + 'dependency would not be cleaned up if its provider is unmounted. ' + 'BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists ' + 'method signatures AND the type shapes of their arguments/returns (do not guess a ' + 'field\'s type; e.g. a bash run\'s stdout is an object, not a string). ' diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index d0db8d7efa..7ee266ce30 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -220,8 +220,6 @@ describe('cordis_mount', () => { return { name: 'raw-register-get', apply(ctx) { - const sp = ctx.get('systemPrompt') - console.log('systemPrompt is', typeof sp) ctx.get('tools').register({ name: 'raw_via_get', description: 'raw', parameters: {}, async execute() { return [] } }) }, } diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts index 50f5b441a2..d3ade92572 100644 --- a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts +++ b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts @@ -154,3 +154,142 @@ describe('sandbox context façade — escape surface is closed', () => { expect(result.isError).toBe(false) }) }) + +describe('sandbox context façade — inject gate on services', () => { + it('denies an undeclared live service (property access), naming the inject fix', async () => { + // `systemPrompt` is a live global service in the setup harness, but this + // mount does not declare it — reaching it would let the mount depend on a + // provider cordis does not know about, so it is refused. + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'undeclared\', inject: [\'tools\'], apply(ctx) { const s = ctx.systemPrompt } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('service "systemPrompt" is not injected') + expect(text(result)).toContain('inject: [\'systemPrompt\', …]') + }) + + it('denies an undeclared live service reached through ctx.get too', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'undeclared-get\', inject: [\'tools\'], apply(ctx) { ctx.get(\'systemPrompt\') } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('service "systemPrompt" is not injected') + }) + + it('allows a service the mount DID declare in inject', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'declared', + inject: ['systemPrompt', 'tools'], + apply(ctx) { console.log('has systemPrompt:', typeof ctx.systemPrompt) } + } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('state: active') + }) + + it('a cross-mount consumer must declare the provider — the undeclared path is refused, not left as a zombie tool', async () => { + // The finding's scenario: a consumer registers a tool built on a provider's + // service WITHOUT declaring inject. cordis would then never park the + // consumer when the provider unmounts, leaving a tool that fails only at + // execution. The gate refuses the undeclared access up front, so the + // dependency is always visible to cordis. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: 'return { name: \'greeter-provider\', apply(ctx) { ctx.provide(\'greeter\', { greet: (n) => \'hi \' + n }) } }', + }) + const undeclared = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'sloppy-consumer', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'greet_undeclared', + description: 'uses greeter without declaring it', + parameters: { n: { type: 'string', required: true } }, + async execute(args) { return [{ type: 'text', text: ctx.greeter.greet(args.n) }] }, + })) + }, + } + `, + }) + // The tool registers (its execute is lazy), but calling it hits the gate: + // `ctx.greeter` is undeclared, so it fails with the teaching error rather + // than silently working and later stranding. + expect(undeclared.isError).toBe(false) + const called = await call(ctx, 'greet_undeclared', { n: 'x' }) + expect(called.isError).toBe(true) + expect(text(called)).toContain('service "greeter" is not injected') + }) +}) + +describe('sandbox tools façade — get is a read-only schema view', () => { + it('ctx.tools.get returns a schema, not the live ToolDefinition with execute', async () => { + // The finding: returning the raw ToolDefinition hands mount code the + // tool's execute function, letting it bypass ToolRegistry.execute (and its + // pre/post hooks). get now returns the same name/description/parameters + // view as schemas(), with no execute. Asserted via a self-made tool that + // reports the shape it saw — world-checked, not self-reported. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'reporter', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'report_view', + description: 'reports the shape of a tool view', + parameters: {}, + async execute() { + const view = ctx.tools.get('cordis_mount') + return [{ type: 'text', text: JSON.stringify({ + hasExecute: 'execute' in view, + hasPresentCall: 'presentCall' in view, + name: view.name, + keys: Object.keys(view).sort(), + }) }] + }, + })) + }, + } + `, + }) + const reported = await call(ctx, 'report_view', {}) + expect(reported.isError).toBe(false) + const shape = JSON.parse(text(reported)) as { hasExecute: boolean; hasPresentCall: boolean; name: string; keys: string[] } + expect(shape.hasExecute).toBe(false) + expect(shape.hasPresentCall).toBe(false) + expect(shape.name).toBe('cordis_mount') + expect(shape.keys).toEqual(['description', 'name', 'parameters']) + }) + + it('ctx.tools.get returns undefined for an unknown tool', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'unknown-probe', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'probe_unknown', + description: 'reports whether an unknown tool resolves', + parameters: {}, + async execute() { + return [{ type: 'text', text: String(ctx.tools.get('no_such_tool') === undefined) }] + }, + })) + }, + } + `, + }) + expect(text(await call(ctx, 'probe_unknown', {}))).toBe('true') + }) +}) From 0ba6d832f80049a6f7c7c89092619296b915b0ac Mon Sep 17 00:00:00 2001 From: pku-xht Date: Thu, 9 Jul 2026 14:19:36 +0800 Subject: [PATCH 090/119] docs: regenerate the module graph on the merged tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The master merge (5309ea54) resolved the module-graph conflict by hand, placing the subagent-subprocess dependency-table row ahead of util/timeout's; the generator's deterministic order (group order, util first) wants them swapped, so the freshness gate (gen-module-graph --check) failed CI's static job. Regenerated on the merged tree — a two-line swap; every other generated catalog was already resolution-fresh (regen-all changed nothing else). --- docs/module-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/module-graph.md b/docs/module-graph.md index 3cb0d6c386..2b606d38db 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -229,8 +229,8 @@ flowchart TD | Package | Group | Depends on | | --- | --- | --- | | [`brand`](../packages/util/brand) | `util` | — | -| [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | — | | [`timeout`](../packages/util/timeout) | `util` | — | +| [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | — | | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — | | [`app-boot`](../packages/ui/app-boot) | `ui` | — | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — | From 1e06fdbb86ecb56d80b4af13fab63de99d320583 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 9 Jul 2026 17:55:01 +0800 Subject: [PATCH 091/119] refactor: colocate user interaction with ui packages --- docs/capability-seams.md | 2 +- docs/config-catalog.md | 2 +- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/user-interaction.md | 4 ++-- docs/module-graph.md | 16 ++++++++-------- .../feature/2026-06-25-ask-user-question.md | 6 +++--- packages/core/README.md | 1 - packages/ui/README.md | 3 ++- packages/ui/acp-agent/tsconfig.json | 2 +- packages/ui/acp/tsconfig.json | 2 +- packages/ui/stdio-agent/tsconfig.json | 2 +- packages/ui/tool-ask-user/tsconfig.json | 2 +- packages/{core => ui}/user-interaction/README.md | 0 .../{core => ui}/user-interaction/package.json | 0 .../{core => ui}/user-interaction/src/index.ts | 0 .../tests/user-interaction.spec.ts | 0 .../{core => ui}/user-interaction/tsconfig.json | 2 +- pnpm-lock.yaml | 12 ++++++------ scripts/type-equiv.manifest.json | 14 +++++++------- tsconfig.build.json | 2 +- tsconfig.json | 2 +- 21 files changed, 38 insertions(+), 38 deletions(-) rename packages/{core => ui}/user-interaction/README.md (100%) rename packages/{core => ui}/user-interaction/package.json (100%) rename packages/{core => ui}/user-interaction/src/index.ts (100%) rename packages/{core => ui}/user-interaction/tests/user-interaction.spec.ts (100%) rename packages/{core => ui}/user-interaction/tsconfig.json (91%) diff --git a/docs/capability-seams.md b/docs/capability-seams.md index dcfa66bde0..caa7f438d7 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -146,7 +146,7 @@ flowchart LR | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. | | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. | | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | -| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/core/user-interaction) | [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. | +| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. | | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 5d04a95ce2..340ae8018b 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -870,7 +870,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-tool-bash` — requires `tools` · `bash` · `systemPrompt` ([`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)) - `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts)) - `@deepseek-ai/dsh-tools` — requires `systemPrompt` ([`packages/core/tools/src/index.ts`](../packages/core/tools/src/index.ts)) -- `@deepseek-ai/dsh-user-interaction` ([`packages/core/user-interaction/src/index.ts`](../packages/core/user-interaction/src/index.ts)) +- `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts)) ## Seam packages (not directly loadable) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 1cd925ed70..968dcd8068 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -235,7 +235,7 @@ registerProvider(provider: UserInteractionProvider): () => void async ask(request: AskUserQuestionRequest): Promise ``` -Source: [`packages/core/user-interaction/src/index.ts:82`](../../packages/core/user-interaction/src/index.ts) +Source: [`packages/ui/user-interaction/src/index.ts:82`](../../packages/ui/user-interaction/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md index 1f8d135a51..6155fd9896 100644 --- a/docs/core-data-structures/user-interaction.md +++ b/docs/core-data-structures/user-interaction.md @@ -1,8 +1,8 @@ # User Interaction -The user-interaction seam of [dsh-user-interaction](../../packages/core/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-agent` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations. +The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-agent` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations. -Source: [`packages/core/user-interaction/src/index.ts`](../../packages/core/user-interaction/src/index.ts) +Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts) ## Question options diff --git a/docs/module-graph.md b/docs/module-graph.md index 8275a48ee8..5ef8313b4e 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -23,7 +23,6 @@ flowchart TD pkg_session["session"] pkg_system_prompt["system-prompt"] pkg_tools["tools"] - pkg_user_interaction["user-interaction"] end subgraph group_bash["packages/bash"] pkg_bash["bash"] @@ -84,6 +83,7 @@ flowchart TD pkg_app_boot["app-boot"] pkg_stdio_agent["stdio-agent"] pkg_tool_ask_user["tool-ask-user"] + pkg_user_interaction["user-interaction"] end subgraph group_code_runtime["packages/code-runtime"] pkg_code_runtime["code-runtime"] @@ -126,8 +126,6 @@ flowchart TD pkg_tools --> pkg_agent pkg_tools --> pkg_llm pkg_tools --> pkg_system_prompt - pkg_user_interaction --> pkg_agent - pkg_user_interaction --> pkg_llm pkg_compact_basic --> pkg_agent pkg_compact_basic --> pkg_compact pkg_compact_basic --> pkg_llm @@ -139,6 +137,8 @@ flowchart TD pkg_invariants --> pkg_agent pkg_invariants --> pkg_llm pkg_invariants --> pkg_session + pkg_user_interaction --> pkg_agent + pkg_user_interaction --> pkg_llm pkg_agent_loop --> pkg_agent pkg_agent_loop --> pkg_llm pkg_agent_loop --> pkg_session @@ -264,11 +264,11 @@ flowchart TD | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) | | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt) | -| [`user-interaction`](../packages/core/user-interaction) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) | | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | +| [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) | | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | @@ -277,8 +277,8 @@ flowchart TD | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | -| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-interaction`](../packages/core/user-interaction) | -| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/core/user-interaction) | +| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | +| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | @@ -288,5 +288,5 @@ flowchart TD | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | -| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`user-interaction`](../packages/core/user-interaction) | -| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`user-interaction`](../packages/core/user-interaction) | +| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`user-interaction`](../packages/ui/user-interaction) | +| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`user-interaction`](../packages/ui/user-interaction) | diff --git a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md index bc041cabc3..9320189de1 100644 --- a/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md +++ b/docs/rfc/implemented/feature/2026-06-25-ask-user-question.md @@ -10,7 +10,7 @@ This is a user-facing capability, but it also crosses package boundaries. A mode ## Decision -Introduce `dsh-user-interaction` as the core interface package for `ctx.userInteraction`, and keep the model-facing consumer `dsh-tool-ask-user` under `packages/ui/tool-ask-user` rather than the core spine. The split is intentional: core owns the abstract seam and stable request/answer/error vocabulary; UI product surfaces own the affordance that asks a human and the concrete provider that collects the answer. The tool registers `ask_user_question`, forwards `{ questions, agent, signal }`, and returns the provider-computed structured answers as the tool result. +Introduce `dsh-user-interaction` as the provider-neutral interface package for `ctx.userInteraction`, colocated with the model-facing consumer `dsh-tool-ask-user` under `packages/ui`. The grouping is intentional: asking a human is a UI-backed product affordance, not part of the providerless core spine. The seam still owns the stable request/answer/error vocabulary, while UI product surfaces provide the concrete provider that collects the answer. The tool registers `ask_user_question`, forwards `{ questions, agent, signal }`, and returns the provider-computed structured answers as the tool result. The model-facing request vocabulary is deliberately aligned with the product-research schema: `ask_user_question({ questions: [{ id, question, header?, options?: [{ label, description? }], multi_select? }] })`. `id` is supplied per question and echoed in the result so a batch can be routed without relying on question text. `label` is both user-facing display text and the selected value returned to the model; there is no separate `value`, no `recommended`, no `allow_custom`, and no `desc` alias. @@ -30,7 +30,7 @@ The ACP mapping deliberately uses elicitation, not `session/request_permission`. **Assistant text followed by a stopped turn.** The model could ask the user in plain assistant text and then stop. That loses the structured option metadata, gives UIs no provider-neutral way to render a choice, and forces the next human answer to arrive as a new user prompt rather than as the result of the operation that needed the answer. -**A core `tool-ask-user` package.** The first implementation put the model-facing tool under `packages/core`, but the tool is not providerless loop infrastructure. It is a product-facing affordance that only works when a UI provider exists, so core owns only the abstract `ctx.userInteraction` seam and the tool lives under `packages/ui`. +**Core-owned ask-user packages.** The first implementation split the seam and the model-facing tool across `packages/core` and `packages/ui`, but both names describe one UI-backed human-interaction affordance. The seam remains provider-neutral, but it is not providerless core infrastructure like sessions, tools, or the agent registry. Keeping `dsh-user-interaction` and `dsh-tool-ask-user` together under `packages/ui` makes the package map match the product boundary: apps and bridges provide the human-answer provider, and the stdio app opts into the model-facing tool. **ACP `session/request_permission`.** Permission requests are authorization around tool execution; `ask_user_question` is information gathering with optional free-form answers. Using permission for general questions would collapse two different product concepts and make the future permission gate harder to reason about. @@ -42,7 +42,7 @@ ACP elicitation is currently marked unstable in the SDK. The fallback is still s The feature gives the model a powerful pause primitive, so prompt guidance matters. The tool description tells the model to ask concise questions and use options when possible. Product policy can later wrap `tools/execute` to restrict when the tool is allowed, but the loop should not special-case it. -`dsh-tool-ask-user` lives in `packages/ui` even though it is a tool, because it is a product-facing human-interaction affordance rather than providerless loop infrastructure. The core package remains only the abstract seam; `agent-core` does not load the tool. `stdio-agent` opts into it alongside its readline provider. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests. +`dsh-user-interaction` and `dsh-tool-ask-user` both live in `packages/ui` because they form one product-facing human-interaction capability. `agent-core` does not load either the tool or a provider. `stdio-agent` opts into the seam, its readline provider, and the model-facing tool. `acp-agent` keeps only the `userInteraction` seam/provider by default: ACP elicitation support is still client-dependent, so an ACP leaf must opt into the model-facing tool deliberately once its client can complete elicitation requests. ## Testing diff --git a/packages/core/README.md b/packages/core/README.md index a2d01aa0df..eee8e3eed0 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -7,7 +7,6 @@ The packages every harness build is assembled from: the session log, the system- | `session/` | Event-sourced session log + in-memory store | `ctx.sessions` | | `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` | | `tools/` | Tool registry + `tools/pre-execute`/`tools/post-execute` pipeline | `ctx.tools` | -| `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` | | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` | | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` | | `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) | diff --git a/packages/ui/README.md b/packages/ui/README.md index 7565d8b418..e87a5e4a10 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -5,6 +5,7 @@ Integrations that expose the agent to an external editor or client. These are ** | Package | Role | ctx key | |---|---|---| | `acp/` | Agent Client Protocol bridge: serves the agent to an ACP editor (Zed) over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) | +| `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` | | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) | | `stdio-agent/` | Terminal stdio chat APP: the agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) | | `acp-agent/` | ACP server APP: the agent-core spine + JSONL persistence + the `acp` bridge (no stdout logger), with a `bin` | (composition + `bin`) | @@ -12,6 +13,6 @@ Integrations that expose the agent to an external editor or client. These are ** A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The readline UI is the unstructured analogue of the `acp` bridge and lives INSIDE the stdio app (the `stdio-chat` module of [`stdio-agent/`](stdio-agent/README.md)): it is scaffolding for that one front door, not an independently swappable integration, so it carries no package boundary of its own. -`tool-ask-user` lives here because it is a model-facing product affordance that depends on a UI/provider seam; it is not part of the providerless core spine. +`user-interaction` and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. The seam remains provider-neutral (`ctx.userInteraction`), while the tool is the model-facing consumer and the app/bridge packages provide concrete providers. `stdio-agent` and `acp-agent` are the two **app packages**: each composes the [`core/agent-core`](../core/agent-core/README.md) spine with its coupled front-door cluster (and owns the boot `bin`), so a leaf `cordis.yml` is the swappable backends plus one app entry plus any optional product tools. They live in `ui/` because each IS a user-facing front door; the stdout-purity coupling (logger vs. no logger) becomes a property of the artifact rather than a leaf convention. diff --git a/packages/ui/acp-agent/tsconfig.json b/packages/ui/acp-agent/tsconfig.json index 1d544ae1c0..13009a2e5c 100644 --- a/packages/ui/acp-agent/tsconfig.json +++ b/packages/ui/acp-agent/tsconfig.json @@ -27,7 +27,7 @@ "path": "../../core/agent-core" }, { - "path": "../../core/user-interaction" + "path": "../user-interaction" }, { "path": "../tool-ask-user" diff --git a/packages/ui/acp/tsconfig.json b/packages/ui/acp/tsconfig.json index 9e24fa0f7a..9c2358c455 100644 --- a/packages/ui/acp/tsconfig.json +++ b/packages/ui/acp/tsconfig.json @@ -30,7 +30,7 @@ "path": "../../core/tools" }, { - "path": "../../core/user-interaction" + "path": "../user-interaction" }, { "path": "../../session-persistence/session-persistence" diff --git a/packages/ui/stdio-agent/tsconfig.json b/packages/ui/stdio-agent/tsconfig.json index 264b1cac4c..6f30c1558e 100644 --- a/packages/ui/stdio-agent/tsconfig.json +++ b/packages/ui/stdio-agent/tsconfig.json @@ -33,7 +33,7 @@ "path": "../../core/agent-core" }, { - "path": "../../core/user-interaction" + "path": "../user-interaction" }, { "path": "../tool-ask-user" diff --git a/packages/ui/tool-ask-user/tsconfig.json b/packages/ui/tool-ask-user/tsconfig.json index 06805c0b8f..c779bad37f 100644 --- a/packages/ui/tool-ask-user/tsconfig.json +++ b/packages/ui/tool-ask-user/tsconfig.json @@ -30,7 +30,7 @@ "path": "../../core/tools" }, { - "path": "../../core/user-interaction" + "path": "../user-interaction" } ] } diff --git a/packages/core/user-interaction/README.md b/packages/ui/user-interaction/README.md similarity index 100% rename from packages/core/user-interaction/README.md rename to packages/ui/user-interaction/README.md diff --git a/packages/core/user-interaction/package.json b/packages/ui/user-interaction/package.json similarity index 100% rename from packages/core/user-interaction/package.json rename to packages/ui/user-interaction/package.json diff --git a/packages/core/user-interaction/src/index.ts b/packages/ui/user-interaction/src/index.ts similarity index 100% rename from packages/core/user-interaction/src/index.ts rename to packages/ui/user-interaction/src/index.ts diff --git a/packages/core/user-interaction/tests/user-interaction.spec.ts b/packages/ui/user-interaction/tests/user-interaction.spec.ts similarity index 100% rename from packages/core/user-interaction/tests/user-interaction.spec.ts rename to packages/ui/user-interaction/tests/user-interaction.spec.ts diff --git a/packages/core/user-interaction/tsconfig.json b/packages/ui/user-interaction/tsconfig.json similarity index 91% rename from packages/core/user-interaction/tsconfig.json rename to packages/ui/user-interaction/tsconfig.json index cf9888627c..178ff39f3f 100644 --- a/packages/core/user-interaction/tsconfig.json +++ b/packages/ui/user-interaction/tsconfig.json @@ -15,7 +15,7 @@ "path": "../../../vendor/cordis" }, { - "path": "../agent" + "path": "../../core/agent" }, { "path": "../../llm/llm" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5ca98009c5..ee5887703e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -320,11 +320,11 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) - packages/core/user-interaction: + packages/ui/user-interaction: devDependencies: '@deepseek-ai/dsh-agent': specifier: workspace:^ - version: link:../agent + version: link:../../core/agent '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm @@ -973,7 +973,7 @@ importers: version: link:../../core/tools '@deepseek-ai/dsh-user-interaction': specifier: workspace:^ - version: link:../../core/user-interaction + version: link:../user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -1003,7 +1003,7 @@ importers: version: link:../../core/system-prompt '@deepseek-ai/dsh-user-interaction': specifier: workspace:^ - version: link:../../core/user-interaction + version: link:../user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) @@ -1060,7 +1060,7 @@ importers: version: link:../tool-ask-user '@deepseek-ai/dsh-user-interaction': specifier: workspace:^ - version: link:../../core/user-interaction + version: link:../user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) @@ -1084,7 +1084,7 @@ importers: version: link:../../core/tools '@deepseek-ai/dsh-user-interaction': specifier: workspace:^ - version: link:../../core/user-interaction + version: link:../user-interaction cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 574d96231a..2d498e8b64 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -48,13 +48,13 @@ { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredSchemaNode", "source": "packages/core/tools/src/json-schema.ts" }, { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredOutputSchema", "source": "packages/core/tools/src/json-schema.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/core/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionItem", "source": "packages/core/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/core/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswerItem", "source": "packages/core/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/core/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/core/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/core/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionItem", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswerItem", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/ui/user-interaction/src/index.ts" }, + { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/ui/user-interaction/src/index.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" }, { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" }, diff --git a/tsconfig.build.json b/tsconfig.build.json index cb01544e96..9f860bbca7 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -19,7 +19,7 @@ { "path": "./packages/session-persistence/session-persistence-sqlite" }, { "path": "./packages/core/system-prompt" }, { "path": "./packages/core/agent" }, - { "path": "./packages/core/user-interaction" }, + { "path": "./packages/ui/user-interaction" }, { "path": "./packages/core/tools" }, { "path": "./packages/ui/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, diff --git a/tsconfig.json b/tsconfig.json index db2ae11298..1afdfa8e46 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -30,7 +30,7 @@ { "path": "./packages/session-persistence/session-persistence-sqlite" }, { "path": "./packages/core/system-prompt" }, { "path": "./packages/core/agent" }, - { "path": "./packages/core/user-interaction" }, + { "path": "./packages/ui/user-interaction" }, { "path": "./packages/core/tools" }, { "path": "./packages/ui/tool-ask-user" }, { "path": "./packages/core/agent-loop" }, From 4a15c8a4794788be27a17d02a6ee1795f83375c9 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 18:13:34 +0800 Subject: [PATCH 092/119] workflow: make the seam's listener containment total MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit emitWorkflowEvent's catch rendered the thrown value with a bare String(error), which itself throws when the value's toString / Symbol.toPrimitive throws — breaking the documented containment guarantee: such a listener could fail the run mid-emit, starve later listeners, and turn the detached workflow/end settle hook into an unhandled rejection. Render through a local total fallback instead (String in a try, a fixed label when even coercion throws); local because the seam sits below every engine and cannot import an engine's renderer. Regression: a listener throwing a coercion-trap value — the emit does not propagate and later listeners still run. --- packages/workflow/workflow/src/index.ts | 31 +++++++++++++++---- .../workflow/workflow/tests/workflow.spec.ts | 16 ++++++++++ 2 files changed, 41 insertions(+), 6 deletions(-) diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 288f6af952..0e5a03c438 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -218,11 +218,12 @@ export abstract class WorkflowService extends Service { * with its OWN structural clone of the payload (the payloads are plain JSON * data by the seam contract), so a listener mutating what it received can * corrupt neither the engine's live state nor any other listener's or later - * event's view; a thrown listener is logged (never propagated), so one bad - * subscriber can neither fail the engine mid-run, surface as an unhandled - * rejection on a detached settle hook, nor starve the listeners registered - * after it (cordis `emit` halts on the first throw — same guarantee as the - * subagent seam's lifecycle emits). + * event's view; a thrown listener is logged (never propagated — the logging + * itself is total, even for a thrown value whose own string coercion + * throws), so one bad subscriber can neither fail the engine mid-run, + * surface as an unhandled rejection on a detached settle hook, nor starve + * the listeners registered after it (cordis `emit` halts on the first throw + * — same guarantee as the subagent seam's lifecycle emits). * @param name - the `workflow/*` event to dispatch. * @param args - the event's payload, matching its declared signature. */ @@ -233,10 +234,28 @@ export abstract class WorkflowService extends Service { // dispatch callback applies the payload tuple. ;(callback as (...payload: unknown[]) => void)(...structuredClone(args)) } catch (error: unknown) { - this.ctx.logger.warn(`workflow: ${name} listener threw: ${String(error)}`) + this.ctx.logger.warn(`workflow: ${name} listener threw: ${renderListenerError(error)}`) } } } } +/** + * Total renderer for a listener-thrown value: the containment catch must never + * itself throw, and `String(error)` does when the value's own `toString` / + * `Symbol.toPrimitive` throws. Local rather than an engine package's renderer + * — the seam sits below every engine and cannot import one. + * @param error - any thrown value. + * @returns `String(error)`, or a fixed label when even coercion throws. + */ +function renderListenerError(error: unknown): string { + try { + return String(error) + } catch { + // Only a throwing toString/Symbol.toPrimitive lands here; the fixed label + // keeps the containment guarantee total. + return '[unrenderable thrown value]' + } +} + export default WorkflowService diff --git a/packages/workflow/workflow/tests/workflow.spec.ts b/packages/workflow/workflow/tests/workflow.spec.ts index b303c02962..a983e5a2b3 100644 --- a/packages/workflow/workflow/tests/workflow.spec.ts +++ b/packages/workflow/workflow/tests/workflow.spec.ts @@ -102,6 +102,22 @@ describe('dsh-workflow (interface)', () => { expect(String(warn.mock.calls[0]![0])).toContain('workflow/phase listener threw') }) + it('containment is total: a listener throwing a value whose coercion throws neither propagates nor starves later listeners', async () => { + const ctx = new Context() + await ctx.plugin(StubEngine) + const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => ctx.logger) + const reached: string[] = [] + ctx.on('workflow/phase', () => { + throw { toString: () => { throw new Error('coercion trap') } } + }) + ctx.on('workflow/phase', (_info, title) => { reached.push(title) }) + const engine = ctx.workflows as StubEngine + expect(() => { engine.emit('workflow/phase', INFO, 'Scan') }).not.toThrow() + expect(reached).toEqual(['Scan']) + expect(warn).toHaveBeenCalledOnce() + expect(String(warn.mock.calls[0]![0])).toContain('[unrenderable thrown value]') + }) + it('has the expected export surface (default = the abstract service class)', () => { expect(WorkflowServiceDefault).toBe(WorkflowService) }) From fbc9eb313c47570294a4cf53b0984276da8e6a00 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 18:16:51 +0800 Subject: [PATCH 093/119] workflow: harden the seam-contract tests ahead of the engine swap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three engine-agnostic pins, landed BEFORE the worker-thread port so the port commit demonstrates contract preservation against them: - tool-workflow: the tool: prompt-section registration was entirely unasserted — assemble() now pins the section present under the CONFIGURED name and gone after fiber dispose (the packages AGENTS.md dispose-and-assert-cleanup rule; tool-bash is the template). - tool-workflow: drop the dead `??` re-defaulting of already- schemastery-resolved config (the hidden-fallback shape AGENTS.md bans) and the direct-apply test that existed only to cover those branches; both engines' `config as ResolvedConfig` is the pattern. - workflow-vm: workflow/end was asserted only on completed runs — the cancelled path and the grace force-settle path now pin the event and its stopReason/error/agentsStarted payload (an observer's only death signal on those paths). --- packages/workflow/tool-workflow/src/index.ts | 7 +++++-- .../tool-workflow/tests/tool-workflow.spec.ts | 19 ++++++++----------- .../workflow-vm/tests/workflow-vm.spec.ts | 12 +++++++++++- 3 files changed, 24 insertions(+), 14 deletions(-) diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts index a5eae80aec..22ab21ffc6 100644 --- a/packages/workflow/tool-workflow/src/index.ts +++ b/packages/workflow/tool-workflow/src/index.ts @@ -49,6 +49,8 @@ export const Config: z = z.object({ maxResultChars: z.natural().min(1).default(50_000), }) +type ResolvedConfig = Required + /** * The script-authoring contract, embedded in the tool description. This IS the * model-facing spec: the meta block, the hooks and their exact semantics, and @@ -120,8 +122,9 @@ function renderResult(run: WorkflowRun, result: WorkflowResult, maxChars: number } export function apply(ctx: Context, config: Config): void { - const maxResultChars = config.maxResultChars ?? 50_000 - const toolName = config.toolName ?? 'workflow' + // schemastery (the exported Config schema) has already filled the defaulted + // fields; the assertion records that resolution, not a hidden fallback. + const { toolName, maxResultChars } = config as ResolvedConfig // Usage policy ships with the tool (the master convention: tool guidance // lives in tool plugins as prompt sections, not in the deployment persona). ctx.systemPrompt.section({ diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts index c9e0cf3713..68daecbe37 100644 --- a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts +++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts @@ -130,17 +130,6 @@ describe('dsh-tool-workflow', () => { expect(engine.disposed).toBe(1) }) - it('applies raw-config fallbacks when loaded without schemastery defaults (direct apply)', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - await ctx.plugin(StubEngine) - // Direct apply with an empty RAW config: the `??` fallbacks resolve the - // tool name and render cap without schemastery having filled them. - toolWorkflow.apply(ctx, {}) - expect(ctx.tools.get('workflow')).toBeDefined() - }) - it('a synchronous engine start throw (parse/meta failure) becomes an isError result', async () => { const { ctx, engine, parent } = await setup() engine.startError = new Error('script must begin with `export const meta = {...}`') @@ -192,8 +181,16 @@ describe('dsh-tool-workflow', () => { const fiber = await ctx.plugin(toolWorkflow, { toolName: 'orchestrate' }) expect(ctx.tools.get('orchestrate')).toBeDefined() expect(ctx.tools.get('workflow')).toBeUndefined() + // The usage-policy prompt section rides the same registration: present + // under the CONFIGURED name (its guidance names the tool it describes)… + const sections = (await ctx.systemPrompt.assemble()).sections + const section = sections.find(s => s.name === 'tool:orchestrate') + expect(section?.text).toContain('orchestrate') + expect(sections.some(s => s.name === 'tool:workflow')).toBe(false) await fiber.dispose() expect(ctx.tools.get('orchestrate')).toBeUndefined() + // …and gone with the fiber — a reload must not leak a stale section. + expect((await ctx.systemPrompt.assemble()).sections.some(s => s.name === 'tool:orchestrate')).toBe(false) }) it('presents a generic pending card titled by the sniffed meta name, with the script as rawInput', async () => { diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index eeda6bf049..bb685f536f 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -5,7 +5,7 @@ import { AgentId } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import SubagentService from '@deepseek-ai/dsh-subagent' import type { SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent' -import type { WorkflowResult, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' +import type { WorkflowResult, WorkflowResultInfo, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' import * as vmEngineModule from '../src/index.ts' import VmWorkflowEngine, { type Config } from '../src/index.ts' @@ -534,6 +534,8 @@ describe('dsh-workflow-vm', () => { it('cancel() aborts in-flight children and settles the run cancelled', async () => { const { ctx, parent, provider } = await setup({ manual: true }) + const ends: WorkflowResultInfo[] = [] + ctx.on('workflow/end', (_info, result) => { ends.push(result) }) const handle = ctx.workflows.start({ script: script("return await agent('long job')"), parent }) await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) handle.cancel('user stopped it') @@ -541,6 +543,9 @@ describe('dsh-workflow-vm', () => { expect(result.stopReason).toBe('cancelled') expect(result.error).toContain('user stopped it') expect(provider.runs[0]!.disposed).toBe(true) + // workflow/end is an observer's only death signal: it fires for a + // cancelled run too, mirroring the settled outcome data. + expect(ends).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: 1 }]) await handle.dispose() }) @@ -787,6 +792,8 @@ describe('dsh-workflow-vm', () => { it('cancel() force-settles the result of a script parked on a promise no hook owns', async () => { const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) + const ends: WorkflowResultInfo[] = [] + ctx.on('workflow/end', (_info, result) => { ends.push(result) }) const handle = ctx.workflows.start({ // No hooks involved: an unsettleable await cancellation cannot reject // — the abandon grace is the only thing that can settle this run. @@ -797,6 +804,9 @@ describe('dsh-workflow-vm', () => { const result = await handle.result expect(result.stopReason).toBe('cancelled') expect(result.error).toContain('user aborted') + // The grace force-settle fires workflow/end exactly like an ordinary + // settlement — an abandoned script's death still reaches observers. + expect(ends).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: 0 }]) await handle.dispose() }) From e41dbe730335b6208db9a56594b8527f37615cf8 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 9 Jul 2026 18:42:51 +0800 Subject: [PATCH 094/119] docs: list the user-interaction packages in the ui/ group summaries --- AGENTS.md | 2 +- packages/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1ef6af2ba0..cce6c18af3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai guard/ loop-hygiene plugins hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends - ui/ ACP bridge + app-boot glue + the stdio/ACP app bins + ui/ ACP bridge, app-boot glue, stdio/ACP app bins, user-interaction seam, ask-user tool support/ dev/test infrastructure packages util/ zero-dependency utilities examples/ Runnable demos: thin cordis.yml leaves over the app packages (see examples/AGENTS.md) diff --git a/packages/README.md b/packages/README.md index bc09826777..220941272a 100644 --- a/packages/README.md +++ b/packages/README.md @@ -21,7 +21,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | -| [`ui/`](ui/README.md) | Editor/client integration surfaces (the ACP bridge) + the app packages | Product — stable surface | +| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, app packages, user-interaction seam, ask-user tool | Product — stable surface | | [`support/`](support/README.md) | Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations | | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded` primitive) | Support — small, stable, harness-dep-free | From db857f62c08404e6767917163a191cdfdba29b1d Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 18:51:44 +0800 Subject: [PATCH 095/119] docs(tool-cordis): state the sandbox stance as steering, not containment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sandbox docs overclaimed a containment contract the design never makes: "capability access is routed through cordis services, never Node built-ins, so everything a mounted plugin does stays inspectable and disposable". The host-realm helpers on the sandbox global (harness, console, btoa) are reachable functions, so mount code that goes looking can reach the host realm through one of them — accepted under the trust stance, because the ctx a mount ultimately receives is fully privileged anyway. Reword the sandbox module doc, the README trust stance, and the RFC sandbox-semantics section to say exactly that: the traps and small global surface STEER honest code onto the cordis services; they are not a security boundary. --- .../2026-07-08-self-referential-cordis-toolset.md | 2 +- packages/cordis/tool-cordis/README.md | 2 +- packages/cordis/tool-cordis/src/sandbox.ts | 13 ++++++++----- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index fff36fee91..8a43c271c3 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -26,7 +26,7 @@ The trust stance, stated once and threaded through the rest: the `node:vm` sandb ### Sandbox semantics -Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through `cordis_inspect` and disposable with its fiber. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). +Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is handed in — capability access is *steered* toward the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing) rather than Node built-ins, so a well-behaved mount stays inspectable through `cordis_inspect` and disposable with its fiber. This is steering, not containment: consistent with the trust stance above, the small global surface keeps *honest* code on the cordis services but is not a security boundary — the host-realm helpers it exposes (`harness`, `console`, `btoa`) are reachable functions, so mount code that goes looking (through such a helper's `.constructor`, say) can still reach the host realm and Node itself, which is accepted because the `ctx` a mount ultimately receives is fully privileged anyway. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (also acceptable under the trust stance). Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md index 651f3273d9..c4f3cf11b9 100644 --- a/packages/cordis/tool-cordis/README.md +++ b/packages/cordis/tool-cordis/README.md @@ -12,7 +12,7 @@ Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-cata ## Trust stance -The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool. +The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. These traps steer honest code onto the cordis services; they do not contain a mount that goes looking — the host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are reachable functions, so mount code can reach the host realm and Node through one of them, which is fine because `ctx` is fully privileged anyway. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool. ## Config diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts index add858f3ce..5ed6b52b50 100644 --- a/packages/cordis/tool-cordis/src/sandbox.ts +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -6,11 +6,14 @@ * routed through cordis services, never Node built-ins: filesystem work goes * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`, * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount) - * — so everything a mounted plugin does stays inspectable and disposable. The - * sandbox guards against ACCIDENTAL global pollution only — it is not a - * security boundary; the `ctx` a mounted plugin's `apply` later receives is - * the real, fully privileged runtime handle, and that is the point of the - * toolset. + * — so a well-behaved mount stays inspectable and disposable. That routing is + * STEERING toward the cordis services, not containment: the sandbox guards + * against ACCIDENTAL global pollution, and it is not a security boundary. The + * host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are + * reachable functions, so a mount that goes looking — e.g. through such a + * helper's `.constructor` — can still reach the host realm; that is accepted, + * because the `ctx` a mounted plugin's `apply` later receives is the real, + * fully privileged runtime handle, and that is the point of the toolset. * * @module @deepseek-ai/dsh-tool-cordis/sandbox */ From f1e54d737b9efc44216020942d468683ac9ebf63 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 19:30:49 +0800 Subject: [PATCH 096/119] =?UTF-8?q?fix(tool-cordis):=20pass=20primitive=20?= =?UTF-8?q?provided=20service=20values=20through=20the=20fa=C3=A7ade?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cordis provide() accepts any value and cross-mount composition advertises ctx.provide('name', value), but the façade's readService unconditionally proxied every declared service — new Proxy('42') throws "Cannot create proxy with a non-object as target or handler", so a consumer of a primitive-valued service crashed on first read with an error naming neither the service nor the fix. A primitive or null value now passes through unwrapped (after the denyContext check); only object- and function-valued services are proxied — a primitive has no method that could hand back a Context, so nothing is lost. New cross-mount spec pins both read paths (ctx. and ctx.get) for a number and a null provided value. --- packages/cordis/tool-cordis/src/guard.ts | 15 ++++++-- .../tool-cordis/tests/cross-mount.spec.ts | 38 +++++++++++++++++++ 2 files changed, 49 insertions(+), 4 deletions(-) diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index b124f6781f..90eaaec41b 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -9,8 +9,9 @@ * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do * exactly four things — register a tool, listen to an event, provide a service, * call an injected service (timers included) — so the façade exposes only those - * verbs and the injected services, each individually wrapped. Every framework - * plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`, + * verbs and the injected services, each object-valued service individually + * wrapped (a primitive provided value passes through as-is — see + * {@link sandboxContext}). Every framework plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`, * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is * DENIED with a teaching error rather than passed through. This closes an * entire escape class at once: a pass-through proxy that only special-cased @@ -284,11 +285,17 @@ function sandboxContext(ctx: Context): Context { // error; a DECLARED one resolves to the guarded service. A declared inject // is required in cordis (the fiber only activates once every declared // service is live), so at `apply`/`execute` time `ctx.get(name)` is present - // for a declared name — no undefined case to handle here. + // for a declared name — no undefined case to handle here. `provide()` + // accepts ANY value though (cross-mount composition advertises + // `ctx.provide('name', value)`), so a primitive or null value passes + // through unwrapped: Proxy throws on a non-object target, and only an + // object can carry a method that hands back a Context. const readService = (name: string): unknown => { if (name === 'tools') return tools if (!declared.has(name)) return denyRead(name) - return guardedService(ctx.get(name) as object, name) + const service = denyContext(ctx.get(name), name) + if (service === null || (typeof service !== 'object' && typeof service !== 'function')) return service + return guardedService(service, name) } const get = (name: string): unknown => readService(name) return new Proxy({}, { diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts index f68eaef639..dcfdb815c4 100644 --- a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts @@ -91,6 +91,44 @@ describe('cross-mount provide/inject', () => { expect(api).toContain('- greeter (provided by greeter-provider, no catalog entry)') }) + it('a primitive (or null) provided value passes through the façade unwrapped, on both read paths', async () => { + const ctx = await setup() + const provider = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'answer-provider', + apply(ctx) { + ctx.provide('answer', 42) + ctx.provide('nothing', null) + }, + } + `, + }) + expect(provider.isError).toBe(false) + + const consumer = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'answer-consumer', + inject: ['answer', 'nothing', 'tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'answer', + description: 'Read the provided primitive services.', + parameters: {}, + async execute() { + return [{ type: 'text', text: ctx.answer + '/' + ctx.get('answer') + '/' + ctx.nothing }] + }, + })) + }, + } + `, + }) + expect(consumer.isError).toBe(false) + expect(text(consumer)).toContain('state: active') + expect(text(await call(ctx, 'answer', {}))).toBe('42/42/null') + }) + it('unmounting the consumer leaves the provider and its service intact', async () => { const ctx = await setup() await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 From b5f618bcfb1ddd95adc82f2f0bac88e4ace52bb3 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 18:39:31 +0800 Subject: [PATCH 097/119] workflow: swap the engine's internals to node:worker_threads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In-place port of dsh-workflow-vm from the in-process node:vm execution to one worker thread per run (the workflow-workerthread engine of PR #215, adopted as THE engine): the script's vm context moves inside the worker, agent() bridges to ctx.subagents over the message port (host.ts/protocol.ts/session.ts/worker.ts are new; runtime.ts loses the abandon channel — the host's grace timer force-settles and TERMINATES instead), start() pre-parses the body host-side to keep the seam's synchronous SCRIPT_PARSE throw, and a ready→go handshake keeps a run cancelled before start from ever executing the body. start() no longer blocks the host, termination is real, and the value boundary is serialization by construction. The package keeps its name until the follow-up rename commit; scripts see the identical hook surface, and the seam-contract tests hardened ahead of this swap pass unchanged. The run and child-RPC surfaces are class-shaped rather than literal bundles: WorkerRun IMPLEMENTS the seam's WorkflowRun (id/meta are its own clone, separate from event payloads') and start() returns the instance directly — interface parity with the seam is compiler-checked; worker-side, ChildRpcBridge (implements ChildPort; callId allocation + pending book-keeping settled by onChild* entry points) and RpcChildHandle (every member an RPC keyed by its callId) carry names in stacks. ChildPort's method is startAgent — it names what it starts, matching the script-side agent() hook and the agentsStarted / workflow/agent-* vocabulary; the Child* type names deliberately stay (the worker side is cordis- and subagent-free; these are reduced JSON projections, not the seam's types). Review findings from the reference PR are folded in rather than re-introduced: - cancel() drives BOTH child-cancel channels host-side: the request signal aborts AND each registered child's explicit cancel() is called — a worker wedged in a synchronous spin cannot relay its own ChildCancel RPCs (regression: cancel-only provider + wedged worker). - All host warn paths render through the total renderThrown; a child dispose() rejecting a value whose coercion throws still acks ChildDisposed instead of wedging the script's finally (regression). - built-worker.e2e.ts is wired into builtBinSmokeGate and the AGENTS.md CI sequence — the built lib/worker.js resolution contract now runs in an automated gate. - workflow/end payload pinned on the worker-death path (with the cancelled and grace-force-settle pins riding the ported spec). - Real-Worker scripted timing budgets widened (50-300ms → 150-1000ms) for starved CI hosts. Workspace plumbing: the "./worker" subpath export sanctions the second runtime bundle (check-workspace-constraints), tsdown builds two single-entry passes, tsx becomes a devDependency for the unbuilt worker spawn. --- AGENTS.md | 2 +- .../tool-workflow/tests/tool-workflow.spec.ts | 6 +- packages/workflow/workflow-vm/README.md | 36 +- packages/workflow/workflow-vm/package.json | 10 +- packages/workflow/workflow-vm/src/host.ts | 384 +++++++ packages/workflow/workflow-vm/src/index.ts | 184 ++-- packages/workflow/workflow-vm/src/protocol.ts | 115 ++ packages/workflow/workflow-vm/src/realm.ts | 27 +- packages/workflow/workflow-vm/src/runtime.ts | 264 ++--- packages/workflow/workflow-vm/src/session.ts | 210 ++++ packages/workflow/workflow-vm/src/types.ts | 97 ++ packages/workflow/workflow-vm/src/worker.ts | 18 + .../workflow-vm/tests/built-worker.e2e.ts | 56 + .../workflow-vm/tests/integration.spec.ts | 14 +- .../workflow-vm/tests/session.spec.ts | 504 +++++++++ .../workflow-vm/tests/workflow-vm.spec.ts | 990 +++++++----------- .../workflow-vm/tests/workflow.e2e.ts | 55 +- .../workflow/workflow-vm/tsdown.config.ts | 32 + pnpm-lock.yaml | 3 + scripts/check-workspace-constraints.ts | 15 +- scripts/run-gates.ts | 4 + 21 files changed, 2073 insertions(+), 953 deletions(-) create mode 100644 packages/workflow/workflow-vm/src/host.ts create mode 100644 packages/workflow/workflow-vm/src/protocol.ts create mode 100644 packages/workflow/workflow-vm/src/session.ts create mode 100644 packages/workflow/workflow-vm/src/types.ts create mode 100644 packages/workflow/workflow-vm/src/worker.ts create mode 100644 packages/workflow/workflow-vm/tests/built-worker.e2e.ts create mode 100644 packages/workflow/workflow-vm/tests/session.spec.ts create mode 100644 packages/workflow/workflow-vm/tsdown.config.ts diff --git a/AGENTS.md b/AGENTS.md index fc33e2f049..eb34d404a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,7 +70,7 @@ printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})' printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE' ls .sessions/_no-cwd/main-session-*.jsonl >/dev/null rm -rf .sessions -pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts +pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/workflow/workflow-vm/tests/built-worker.e2e.ts ``` `test:coverage`, not `test`, is the gating run ([why](docs/testing.md)); a sign-off counts only for commands actually run. diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts index 68daecbe37..2b6503cd45 100644 --- a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts +++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts @@ -10,7 +10,7 @@ import { WorkflowRunId, WorkflowService } from '@deepseek-ai/dsh-workflow' import type { WorkflowResult, WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' import { CallId } from '@deepseek-ai/dsh-llm' import SubagentService from '@deepseek-ai/dsh-subagent' -import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' +import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' import * as toolWorkflow from '../src/index.ts' /** A controllable engine standing in behind ctx.workflows (the tool's only seam). */ @@ -221,7 +221,7 @@ describe('dsh-tool-workflow', () => { expect(typeof unwrapped.apply).toBe('function') }) - describe('composition with the REAL vm engine (the mock above must stay honest)', () => { + describe('composition with the REAL worker-thread engine (the mock above must stay honest)', () => { it('an abort releases the tool even when the script parks on a promise no hook owns', async () => { // Regression for the review-found turn wedge: the tool awaits // run.result BEFORE its disposing finally, the registry and the loop @@ -234,7 +234,7 @@ describe('dsh-tool-workflow', () => { await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRegistry) await ctx.plugin(SubagentService) - await ctx.plugin(VmWorkflowEngine, { disposeGraceMs: 30 }) + await ctx.plugin(WorkerWorkflowEngine, { disposeGraceMs: 30 }) await ctx.plugin(toolWorkflow, {}) const parent = { id: AgentId('caller'), options: {} } as unknown as Agent const controller = new AbortController() diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-vm/README.md index e29073c2b3..9a0ab21fef 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-vm/README.md @@ -1,34 +1,48 @@ # @deepseek-ai/dsh-workflow-vm -The first [`WorkflowService`](../workflow/README.md) implementation: an in-process **`node:vm` engine**. It parses the Claude Code-format script (`export const meta = {...}` + plain-JS body), runs the body in a fresh vm context with the workflow hooks injected, and fans `agent()` calls out to [`ctx.subagents`](../../subagent/README.md). +The [`WorkflowService`](../workflow/README.md) implementation, on **`node:worker_threads`**: each run gets its OWN worker thread (one run = one worker, no pooling — a run is heavyweight, so the ~tens-of-ms thread spin-up is noise), the script executes in a vm context INSIDE that worker with the workflow hooks injected, and every `agent()` call bridges back over the message port to [`ctx.subagents`](../../subagent/README.md) on the host. Child agents are I/O-bound LLM loops and stay on the host event loop; the thread isolates the SCRIPT, the only part that can spin synchronously. -## Trust premise +## Trust premise: what the thread buys (and what it does not) -Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. vm is NOT a security boundary and no attempt is made to contain adversarial values: property reads on script values may run script code (a getter, a `toString`, a proxy trap) on the host stack, and a script determined to hang the process can simply spin past its first await (see the limitations below). Concretely, the context is **escapable by construction**: `node:vm` shares object machinery with the host, so a script can reach the host `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin — the absent globals are API surface that keeps honest scripts portable, not walls. What the engine DOES guarantee, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection (the app boot layer exits the process on those), values that JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing is an engine swap behind the seam (worker-thread/isolated-vm, where the boundary is serialization by construction), not incremental host-side defenses here. +Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. A worker thread is NOT a security boundary: the vm context inside it is escapable by construction (`node:vm` shares object machinery with its surrounding realm, so a script can reach the `Function` constructor via `globalThis.constructor.constructor` and from it `process` and every Node builtin), and an escapee holds the same process privileges as the host — Node's permission model is process-wide. The absent globals are API surface that keeps honest scripts portable, not walls. What the thread concretely buys: + +- **The host never blocks**: `start()` returns without running any script code on the host; a synchronous spin anywhere in the script occupies the worker's loop, not the harness's. +- **Termination is real**: a script that outlives its post-cancel grace is `worker.terminate()`d — nothing of it survives `dispose()`, where an in-process engine could only abandon the spin on its own loop. +- **Serialization by construction**: everything crossing the thread is structured-clone data, and plain JSON before that — the `materializeFromRealm` walk rejects loud what JSON cannot carry, which is also what makes every postMessage hop total. + +What the seam guarantees regardless, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection, values JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing (containing what an escaped script may touch) remains an isolated-vm/separate-process engine swap behind the seam, still deferred. ## The script contract it executes -- **Meta extraction** (`extractMeta`): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. +- **Meta extraction** (`extractMeta`, host-side): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. - **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline). - **No ambient APIs**: no timers, filesystem, or Node APIs are injected into the context (absence is API surface, not containment — see the trust premise). +## How a run executes + +`start()` extracts and validates the meta HOST-side and parse-checks the body with the identical wrapper the worker compiles (`new vm.Script`, discarded), preserving the seam's synchronous `SCRIPT_PARSE`/`META_INVALID` throws; one redundant parse per run is the deliberate price. It then spawns the worker (`src/worker.ts` unbuilt via an explicit tsx `execArgv`; the sibling `lib/worker.js` bundle when built) with the meta, blanked body, `args`, and worker-side limits as `workerData`. + +Inside the worker, `runWorkerSession` builds the execution core (hooks, combinators, concurrency semaphore, caps, fatal-error discipline) over a **child port**: `agent()` sends `child-start` and the host starts the child on `ctx.subagents` (parent attribution, the shared per-run abort signal, `outputSchema`/`model` pass-through), replying with the child id, its settlement (a JSON projection; an infrastructure REJECTION crosses as `child-failed` and stays the fatal `AGENT_RESULT`), and dispose acks. Observer narration (`phase`/`log`/`agent-start`/`agent-end`) crosses as messages and re-emits as the seam's `workflow/*` events. A **ready→go handshake** gates the body: a cancellation racing worker boot arrives before `go`, so a run cancelled before start never executes the body at all. + ## The value boundary -Values ENTERING the host (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into host containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Getters are read ordinarily — the RESULT is what crosses; a read that throws fails loud. Values ENTERING the realm (`args`, `agent()` results, hook promises and their failures, combinator arrays) are handed over directly as host values — the script is trusted, so host prototypes are not a leak; `args` is `structuredClone`d once at start so a script scribbling on it cannot mutate the caller's object. One script-visible consequence: an error thrown by a hook is a HOST error, so `e instanceof Error` inside the script is `false` — branch on `e.name`/`e.code` instead (the combinators recognize fatality by host `instanceof`, which a script-built object can never pass, so fatal-vs-null cannot be forged or dissolved). +Values LEAVING the script (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into plain containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Getters are read ordinarily — the RESULT is what crosses; a read that throws fails loud. Values ENTERING the realm (`args`, `agent()` results, hook promises and their failures, combinator arrays) are handed over directly as worker-realm values — the script is trusted, so outer prototypes are not a leak; `args` is cloned once at start so a script scribbling on it cannot mutate the caller's object. One script-visible consequence: an error thrown by a hook is built OUTSIDE the script's vm context, so `e instanceof Error` inside the script is `false` — branch on `e.name`/`e.code` instead (the combinators recognize fatality by `instanceof` against their own realm's class, which a script-built object can never pass, so fatal-vs-null cannot be forged or dissolved). -## Limits, cancellation, disposal +## Cancellation, death, disposal -Per-run: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` aborts every child (a shared `AbortSignal`), rejects waiting `agent()` slots, and makes every future hook call throw `CANCELLED` — the script dies at its next await and the run settles `cancelled`; a cancellation that lands before the body runs (or before it settles) reports `cancelled` even if the script itself needed no hooks, and a script that STILL has not settled `disposeGraceMs` after the cancel (parked on a promise no hook owns, like `await new Promise(() => {})`) is ABANDONED with `result` force-settling `cancelled` — a consumer awaiting `result` is never wedged past a cancellation. Once a run settles, stray children a script fired without awaiting are aborted too, and `dispose()` waits for those children to finish disposing (bounded by the grace) before returning. Every hook-returned promise carries a no-op rejection consumer, so a dropped promise cannot surface an unhandled rejection; thrown script values are rendered by a total host-side renderer (stack, then message, then `String()`, with a fixed label if rendering itself throws) — `result` cannot reject. +Per-run limits: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` posts the cancel to the worker (its hooks start throwing `CANCELLED`; the script dies at its next await) and cancels every host-side child NOW on **both seam channels** — the shared request signal aborts AND each registered child's explicit `cancel()` is called host-side, because the seam leaves a provider free to honor either channel and a worker wedged in a synchronous spin could not relay its own per-child cancel RPCs (those later land as idempotent no-ops). The grace then arms: a run still unsettled `disposeGraceMs` later force-settles `cancelled` and the worker is **terminated**. A cancellation that lands before the body runs (the ready→go handshake) reports `cancelled` without executing anything; a worker `result` racing an in-flight host cancellation reports `cancelled` too (first-wins settlement — the seam-visible result had not settled when cancellation was requested); post-cancel `phase`/`log` narration is suppressed host-side, while cancelled children still deliver their paired `agent-end`. -**Documented limitations** (the accepted cost of the in-process mechanism; the seam exists so a worker-thread/isolated-vm engine can swap in): `start()` runs the script's initial synchronous slice inline, so the caller blocks until the first await or the vm `timeout`; that `timeout` covers ONLY the initial slice, so a synchronous spin past it (an await continuation, a thenable's `then` invoked by promise resolution, or script code the host runs while rendering a thrown value) cannot be killed; `dispose()` waits `disposeGraceMs` then ABANDONS such a script (its settlement stays contained, but an abandoned spin would still occupy the event loop). A returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — and the value-boundary guard applies to the resolution. +A worker that dies unexpectedly (an OOM, a script reaching `process.exit` through the documented vm escape) settles the run `stopReason: 'error'` with the exit diagnostics — or `'cancelled'` when a cancel was in flight — and the host-side child registry is what winds every surviving child down. `dispose()` = cancel + bounded wait (result, then child-registry quiescence, capped by the grace) + unconditional `worker.terminate()`: the thread never outlives its run. Once a run settles, stray children a script fired without awaiting are cancelled too, and `dispose()` waits for their disposal (bounded by the grace) before returning. + +**Engine-specific limitations**: worker startup is paid per run; on a termination path `agentsStarted` reports the HOST-observed count (accepted `child-start`s — calls still queued worker-side for a concurrency slot are unknowable then); and a returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — with the value-boundary guard applying to the resolution. ## Config | Key | Default | Meaning | |---|---|---| -| `provider` | `spawn` | The `ctx.subagents` provider children run on. | +| `provider` | `spawn` | The `ctx.subagents` provider children run on (host-side). | | `maxConcurrentAgents` | `0` (auto) | Concurrent `agent()` ceiling; `0` resolves to `min(16, max(1, cores - 2))`. | | `maxTotalAgents` | `1000` | Total `agent()` calls one run may start (runaway-loop backstop). | | `maxItemsPerCall` | `4096` | Items accepted by one `parallel()`/`pipeline()` call. | -| `syncTimeoutMs` | `5000` | vm timeout for the initial synchronous slice and the meta evaluation. | -| `disposeGraceMs` | `5000` | How long `dispose()` waits for a cancelled script and its children before abandoning them. | +| `syncTimeoutMs` | `5000` | vm timeout for the initial synchronous slice (in the worker) and the host-side meta evaluation. | +| `disposeGraceMs` | `5000` | How long a cancelled run may stay unsettled before force-settle + terminate; also bounds `dispose()`. | diff --git a/packages/workflow/workflow-vm/package.json b/packages/workflow/workflow-vm/package.json index 8b1217acc0..a174893b9c 100644 --- a/packages/workflow/workflow-vm/package.json +++ b/packages/workflow/workflow-vm/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-workflow-vm", - "description": "node:vm workflow engine: executes model-written orchestration scripts over ctx.subagents", + "description": "worker-thread workflow engine: executes model-written orchestration scripts off the host event loop, bridging agent() calls back to ctx.subagents", "version": "0.0.1", "private": true, "type": "module", @@ -11,11 +11,16 @@ "types": "./lib/types/index.d.ts", "default": "./lib/index.js" }, + "./worker": { + "types": "./lib/types/worker.d.ts", + "default": "./lib/worker.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, "files": [ "lib/index.js", + "lib/worker.js", "lib/types/**/*.d.ts", "lib/types/**/*.d.ts.map", "src" @@ -45,6 +50,7 @@ "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-workflow": "workspace:^", - "cordis": "^4.0.0-rc.6" + "cordis": "^4.0.0-rc.6", + "tsx": "^4.19.2" } } diff --git a/packages/workflow/workflow-vm/src/host.ts b/packages/workflow/workflow-vm/src/host.ts new file mode 100644 index 0000000000..b329e0c7d2 --- /dev/null +++ b/packages/workflow/workflow-vm/src/host.ts @@ -0,0 +1,384 @@ +/** + * The host half of one worker-engine run: spawn the Worker, bridge its child + * RPC onto `ctx.subagents`, fan its observer messages into the engine's + * events, and own cancellation, the settle-within-grace guarantee, and child + * cleanup. The worker's lifetime IS the run's lifetime: `dispose()` always + * ends with `worker.terminate()`, so no thread outlives its run. + * + * The run's `result` promise settles exactly once, from whichever of these + * lands first: the worker's `result` message (a host-side cancellation in + * flight overrides a non-cancelled report — the seam-visible result had not + * settled when cancellation was requested), an unexpected worker death + * (`error`/`messageerror`/premature `exit` → `stopReason: 'error'`, or + * `'cancelled'` when a cancel was in flight), or the post-cancel grace timer + * (a script that never settles is force-settled `cancelled` and its worker + * terminated — the real kill an in-process engine could not perform). + * + * Children live in a host-side registry (callId → run): the worker drives + * their disposal by RPC on the graceful path, and the registry is what lets + * the host abort and dispose every survivor when the worker dies or is + * terminated mid-flight. On a termination path `agentsStarted` reports the + * HOST-observed count (accepted `child-start` messages) — `agent()` calls + * still queued worker-side for a concurrency slot are unknowable then; the + * worker's own count rides the result message on every graceful path. + * + * @module @deepseek-ai/dsh-workflow-vm/host + */ + +import { fileURLToPath } from 'node:url' +import { Worker } from 'node:worker_threads' +import type { WorkerOptions } from 'node:worker_threads' +import type { Context } from 'cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { assertNever } from '@deepseek-ai/dsh-llm' +import type { SubagentRun } from '@deepseek-ai/dsh-subagent' +import type { WorkflowMeta, WorkflowResult, WorkflowRun, WorkflowRunId } from '@deepseek-ai/dsh-workflow' +import { renderThrown } from './realm.ts' +import type { ExecutionObserver } from './runtime.ts' +import { HostToWorkerType, WorkerToHostType } from './protocol.ts' +import type { HostToWorkerPayloads, WorkerToHostMessage } from './protocol.ts' +import type { ChildStartRequest, WorkerInit } from './types.ts' + +/** + * Resolve the worker entry and spawn options for the current runtime shape. + * Unbuilt (tsx demos, vitest — `import.meta.url` points into `src/`), the + * entry is the TypeScript sibling and the worker needs the tsx loader + * registered explicitly: a worker thread inherits no transform pipeline from + * vitest (vite transforms in-process, not via a node loader), and passing + * execArgv explicitly also shields the worker from any loader flags the + * parent was started with. Built (`lib/index.js`), the entry is the sibling + * bundle the package tsdown config emits and no loader is needed. + * @param init - the run payload, passed as `workerData`. + * @returns the entry URL and the Worker options to spawn it with. + */ +function resolveWorkerSpawn(init: WorkerInit): { entry: URL; options: WorkerOptions } { + /* v8 ignore next 3 -- the built-output arm: tests always run unbuilt (src/); the built-worker e2e exercises this shape for real */ + if (!import.meta.url.endsWith('.ts')) { + return { entry: new URL('./worker.js', import.meta.url), options: { workerData: init } } + } + // Lazy tsx resolution: only the unbuilt shape needs it, so the built + // bundle never requires tsx to be installed. + return { + entry: new URL('./worker.ts', import.meta.url), + options: { workerData: init, execArgv: ['--import', fileURLToPath(import.meta.resolve('tsx'))] }, + } +} + +/** + * One live worker-engine run — the seam's {@link WorkflowRun}, returned by + * `start()` directly. Owns the Worker, the child registry, and the result + * settlement; `result` never rejects. `meta` is this handle's OWN clone + * (event payloads carry separate clones), so a consumer mutating it corrupts + * nothing. + */ +export class WorkerRun implements WorkflowRun { + /** Settles exactly once with the run's outcome; never rejects. */ + readonly result: Promise + private settleResolve!: (result: WorkflowResult) => void + private settled = false + private cancelReason: string | undefined + private graceTimer: NodeJS.Timeout | undefined + private readonly worker: Worker + /** Set on `exit`: the thread is gone, so posting has nowhere to go. */ + private workerGone = false + /** Accepted `child-start` messages — the terminate-path `agentsStarted` (see module doc). */ + private hostStarted = 0 + /** Live children by callId; an entry leaves ONLY after its dispose settles (quiescence = empty). */ + private readonly children = new Map() + private readonly quiescenceWaiters: (() => void)[] = [] + /** The per-run abort fanout every child start request carries. */ + private readonly controller = new AbortController() + private disposed: Promise | undefined + + constructor( + private readonly ctx: Context, + readonly id: WorkflowRunId, + readonly meta: WorkflowMeta, + private readonly parent: Agent, + init: WorkerInit, + private readonly provider: string, + private readonly disposeGraceMs: number, + private readonly observer: ExecutionObserver, + signal: AbortSignal | undefined, + ) { + this.result = new Promise((resolve) => { this.settleResolve = resolve }) + // workerData rides the structured clone: args are plain JSON by the seam + // contract, so the clone is total and doubles as the caller-isolation + // copy (a clone failure throws loud out of start()). + const { entry, options } = resolveWorkerSpawn(init) + this.worker = new Worker(entry, options) + this.worker.on('message', (message: WorkerToHostMessage) => { this.onMessage(message) }) + this.worker.on('error', (error) => { this.onWorkerDeath(`workflow worker failed: ${renderThrown(error)}`) }) + /* v8 ignore next -- messageerror: not constructible from the engine's own protocol (every payload is JSON data) */ + this.worker.on('messageerror', (error) => { this.onWorkerDeath(`workflow worker message failed to deserialize: ${renderThrown(error)}`) }) + this.worker.on('exit', (code) => { + this.workerGone = true + this.onWorkerDeath(`workflow worker exited before the run settled (exit code ${code})`) + }) + if (signal?.aborted) { + this.cancel('workflow start signal already aborted') + } else { + signal?.addEventListener('abort', () => { this.cancel('workflow signal aborted') }, { once: true }) + } + } + + /** + * Cancel the run: the worker is told (its hooks start throwing and the + * script dies at its next await), every host-side child is cancelled NOW on + * BOTH seam channels — the shared request signal aborts and each registered + * child's explicit `cancel()` is called (the seam leaves a provider free to + * honor either, and a worker wedged in a synchronous spin could not relay + * its own per-child cancel RPCs until far too late) — and the grace timer + * arms: a run still unsettled `disposeGraceMs` later force-settles + * `cancelled` and its worker is TERMINATED. Idempotent; the first reason + * wins. + * @param reason - human-readable cause (default `'workflow cancelled'`). + */ + cancel(reason?: string): void { + // A settled run has nothing left to cancel: without this guard the + // ordinary consumer path (await result, then dispose -> cancel) would arm + // a grace timer nothing ever clears, pinning the run and its Worker + // closure until the grace expires - a bounded leak per completed run. + if (this.settled || this.cancelReason !== undefined) return + this.cancelReason = reason ?? 'workflow cancelled' + this.post(HostToWorkerType.Cancel, { reason: this.cancelReason }) + this.controller.abort(this.cancelReason) + // The explicit channel is driven host-side, not left to the worker: a + // provider honoring only run.cancel() must not wait on a wedged worker's + // ChildCancel relay (those later RPCs land as idempotent no-ops). + for (const run of this.children.values()) run.cancel(this.cancelReason) + this.graceTimer = setTimeout(() => { + this.settleResult(this.cancelledResult(this.hostStarted)) + void this.worker.terminate() + }, this.disposeGraceMs) + // unref'd: an armed grace timer must never hold the process open. + this.graceTimer.unref() + } + + /** + * Cancel + bounded settle + termination. Waits (at most the grace) for the + * result and child quiescence, then terminates the worker unconditionally + * — the thread never outlives its run — and reaps whatever children + * remain (their disposal is contained, not awaited past the grace, the + * same abandonment the seam documents for a slow-disposing child). + * Idempotent; safe on every path. + * @returns resolves when the run's resources are released or abandoned. + */ + dispose(): Promise { + this.disposed ??= (async () => { + this.cancel('workflow disposed') + await Promise.race([ + (async () => { + await this.result + await this.childQuiescence() + })(), + sleep(this.disposeGraceMs), + ]) + await this.worker.terminate() + this.reapChildren('workflow disposed') + })() + return this.disposed + } + + /** Post one message to the worker (payload looked up from the tag's map entry), tolerating a thread that is already gone. */ + private post(type: T, payload: HostToWorkerPayloads[T]): void { + if (this.workerGone) return + try { + this.worker.postMessage({ type, ...payload }) + } catch (error: unknown) { + // Only a teardown race can land here (every engine message is JSON + // data, so serialization cannot fail); there is nothing left to + // deliver to — log and move on. + /* v8 ignore next -- postMessage teardown race (a throw between exit and its event): not constructible in-process */ + this.ctx.logger.warn(`workflow-vm: postMessage failed: ${renderThrown(error)}`) + } + } + + private onMessage(message: WorkerToHostMessage): void { + switch (message.type) { + case WorkerToHostType.Ready: + this.post(HostToWorkerType.Go, {}) + break + case WorkerToHostType.Phase: + // Post-cancel narration is suppressed host-side: worker-side the + // hooks throw once the cancel message is PROCESSED, but narration + // already in flight (or emitted while the cancel crossed the + // boundary) must not reach observers — nothing is emitted after + // cancel() returns. + if (this.cancelReason === undefined) this.observer.phase(message.title) + break + case WorkerToHostType.Log: + if (this.cancelReason === undefined) this.observer.log(message.message) + break + case WorkerToHostType.AgentStart: + this.observer.agentStart(message.info) + break + case WorkerToHostType.AgentEnd: + // NOT suppressed on cancel: cancelled children report their paired + // agent-end with outcome 'cancelled' (the one-pair-per-started-child + // contract holds on every stop path). + this.observer.agentEnd(message.info) + break + case WorkerToHostType.ChildStart: + this.onChildStart(message.callId, message.request) + break + case WorkerToHostType.ChildCancel: + this.children.get(message.callId)?.cancel(message.reason) + break + case WorkerToHostType.ChildDispose: + this.onChildDispose(message.callId) + break + case WorkerToHostType.Result: + this.onResult(message.result) + break + /* v8 ignore next 2 -- closed engine-owned union; the arm only makes adding a message type a compile error */ + default: + assertNever(message, 'worker-to-host message') + } + } + + private onChildStart(callId: number, request: ChildStartRequest): void { + if (this.cancelReason !== undefined) { + // The worker's start raced our cancel: refuse — a child must never + // start on an already-aborted signal (a provider subscribing only to + // future abort events would never observe it). + this.post(HostToWorkerType.ChildStartError, { callId, rendered: `workflow run cancelled: ${this.cancelReason}` }) + return + } + this.hostStarted += 1 + let run: SubagentRun + try { + run = this.ctx.subagents.start(this.provider, { + prompt: [{ type: 'text', text: request.prompt }], + parent: this.parent, + signal: this.controller.signal, + ...request.schema !== undefined ? { outputSchema: request.schema } : {}, + ...request.model !== undefined ? { agentOptions: { model: request.model } } : {}, + }) + } catch (error: unknown) { + this.post(HostToWorkerType.ChildStartError, { callId, rendered: renderThrown(error) }) + return + } + this.children.set(callId, run) + this.post(HostToWorkerType.ChildStarted, { callId, childId: run.id }) + run.result.then( + (result) => { + this.post(HostToWorkerType.ChildSettled, { + callId, + result: { + output: result.output, + ...result.structured !== undefined ? { structured: result.structured } : {}, + stopReason: result.stopReason, + }, + }) + }, + (error: unknown) => { this.post(HostToWorkerType.ChildFailed, { callId, rendered: renderThrown(error) }) }, + ) + } + + private onChildDispose(callId: number): void { + const run = this.children.get(callId) + /* v8 ignore next 5 -- dispose RPC for an already-reaped child: only a worker-death race can produce it, not orderable in-process */ + if (run === undefined) { + // Already reaped — the ack is still owed (the worker-side wrapper awaits it). + this.post(HostToWorkerType.ChildDisposed, { callId }) + return + } + void run.dispose().then( + () => { + this.finishChild(callId) + this.post(HostToWorkerType.ChildDisposed, { callId }) + }, + (error: unknown) => { + // The subagent seam's dispose() is not supposed to reject; a backend + // that does anyway must not wedge the script's finally (which awaits + // the ack) — ack and move on. + this.ctx.logger.warn(`workflow-vm: child dispose failed: ${renderThrown(error)}`) + this.finishChild(callId) + this.post(HostToWorkerType.ChildDisposed, { callId }) + }, + ) + } + + /** Drop a child from the registry, releasing quiescence waiters at zero. */ + private finishChild(callId: number): void { + this.children.delete(callId) + if (this.children.size === 0) { + for (const waiter of this.quiescenceWaiters.splice(0)) waiter() + } + } + + /** Resolves once the child registry is empty (every disposal settled). */ + private childQuiescence(): Promise { + if (this.children.size === 0) return Promise.resolve() + return new Promise((resolve) => { this.quiescenceWaiters.push(resolve) }) + } + + /** Abort + dispose every registered child (worker death / final teardown); disposal is contained, not awaited. */ + private reapChildren(reason: string): void { + this.controller.abort(this.cancelReason ?? reason) + for (const [callId, run] of [...this.children]) { + run.cancel(this.cancelReason ?? reason) + void run.dispose().then( + () => { this.finishChild(callId) }, + (error: unknown) => { + this.ctx.logger.warn(`workflow-vm: child dispose failed during reap: ${renderThrown(error)}`) + this.finishChild(callId) + }, + ) + } + } + + private onResult(result: WorkflowResult): void { + // The worker's settle-reap already child-cancel()s every stray; this + // abort fires the seam signal too, for providers that only honor the + // request signal (both channels, on every path). + if (this.cancelReason === undefined) this.controller.abort('workflow settled') + if (this.cancelReason !== undefined && result.stopReason !== 'cancelled') { + // The script settled while our cancel was crossing the thread boundary + // — the seam-visible result had NOT settled when cancellation was + // requested, so report cancelled (the vm drive()'s post-settle check, + // relocated to the receiving side of the race). + this.settleResult(this.cancelledResult(result.agentsStarted)) + return + } + this.settleResult(result) + } + + /** An unexpected worker death (or the expected exit after termination). */ + private onWorkerDeath(message: string): void { + // Whatever the worker left behind must not leak — abort + dispose it all. + if (this.children.size > 0) this.reapChildren('workflow worker gone') + // settleResult no-ops on an already-settled run (the expected exit after + // a dispose's terminate lands here too). + if (this.cancelReason !== undefined) { + this.settleResult(this.cancelledResult(this.hostStarted)) + return + } + this.settleResult({ value: null, stopReason: 'error', error: message, agentsStarted: this.hostStarted }) + } + + private cancelledResult(agentsStarted: number): WorkflowResult { + // cancel() is the only writer of cancelReason and every caller checks it + // first; the fallback guards the type, not a reachable path. + /* v8 ignore next */ + const reason = this.cancelReason ?? 'workflow cancelled' + return { value: null, stopReason: 'cancelled', error: `workflow run cancelled: ${reason}`, agentsStarted } + } + + /** First settle wins; disarms the grace timer. */ + private settleResult(result: WorkflowResult): void { + if (this.settled) return + this.settled = true + clearTimeout(this.graceTimer) + this.settleResolve(result) + } +} + +/** A plain timer sleep (the dispose grace); unref'd so it never holds the process open. */ +function sleep(ms: number): Promise { + return new Promise((resolve) => { + const timer = setTimeout(resolve, ms) + timer.unref() + }) +} diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-vm/src/index.ts index c1300427a2..1b65381bfb 100644 --- a/packages/workflow/workflow-vm/src/index.ts +++ b/packages/workflow/workflow-vm/src/index.ts @@ -1,39 +1,37 @@ /** - * The `node:vm` workflow engine: the first {@link WorkflowService} - * implementation. Parses the Claude Code-format script (meta + body), runs the - * body in a fresh in-process vm context with the workflow hooks injected, and - * fans `agent()` calls out to `ctx.subagents`. + * The `node:worker_threads` workflow engine: the {@link WorkflowService} + * implementation. Runs each script in its OWN worker thread (one run = one + * worker, no pooling — a run is heavyweight, so thread spin-up is noise): the + * body executes in a vm context INSIDE the worker with the workflow hooks + * injected, and `agent()` calls bridge back to `ctx.subagents` over the + * message port — child agents are I/O-bound LLM loops and stay on the host + * event loop; the thread isolates the SCRIPT, the only part that can spin + * synchronously. * * TRUST PREMISE: scripts are MODEL-WRITTEN — the same trust level as the * model's existing bash access — so this engine defends against BUGGY - * scripts, never hostile ones. vm is NOT a security boundary and no attempt - * is made to contain adversarial values (see ./realm.ts); the context is - * escapable by construction (the host `Function` constructor is reachable via - * `globalThis.constructor.constructor`, and `process` from there), so the - * absent globals are API surface, not containment. Genuine sandboxing is an - * engine swap behind the seam (worker-thread/isolated-vm), not incremental - * host-side defenses here. + * scripts, never hostile ones. A worker thread is NOT a security boundary: + * the vm context inside it is escapable by construction, and an escapee + * holds the same process privileges as the host (Node's permission model is + * process-wide); genuine sandboxing (isolated-vm, a separate process) is an + * engine swap behind the seam. What the thread buys, concretely: * - * Engine limitations, documented as the accepted cost of the in-process - * mechanism: + * - `start()` never blocks the host: the script's initial synchronous slice + * (and any later synchronous spin) occupies the WORKER's event loop, not + * the harness's. + * - Termination is REAL: a script that outlives its post-cancel grace is + * `worker.terminate()`d — nothing of the script survives `dispose()`, + * where an in-process engine could only abandon the spin on its own loop. + * - The value boundary is serialization by construction: everything crossing + * the thread is structured-clone data (and plain JSON before that, by the + * materialization walk in ./realm.ts). * - * - `start()` runs the script's initial SYNCHRONOUS slice inline, so the - * CALLER blocks on the host event loop until the script's first await (or - * the vm `timeout` kills the slice); the meta-literal evaluation has its - * own timeout budget on the same call. - * - The vm `timeout` covers only that initial slice; realm code running past - * it — an await continuation, a thenable's `then` invoked by promise - * resolution (including one the script RETURNS: a returned thenable - * resolves per JavaScript semantics before materialization, which is what - * makes an un-awaited `return agent('x')` work) — is beyond the timeout, so - * a synchronous spin there cannot be killed in-process, and neither can - * script code the host invokes while rendering a failure (a getter on a - * thrown value). `dispose()` waits a bounded grace for the script to settle - * AND its children (stray `agent()` calls included) to finish disposing, - * then ABANDONS whatever is left: pending hook promises are already - * rejected and the script's settlement is contained (no unhandled - * rejection), but an abandoned synchronous spin would still occupy the - * event loop. + * Engine-specific limitations: worker startup (~tens of ms) is paid per run; + * on a termination path `agentsStarted` reports the host-observed child + * count (calls still queued worker-side for a slot are unknowable — see + * ./host.ts); and a worker that dies unexpectedly (an OOM, a script reaching + * `process.exit` through the documented vm escape) settles the run + * `stopReason: 'error'` with the exit diagnostics. * * Plugin export shape: a default-exported {@link WorkflowService} subclass * (the class-based service form, like `dsh-bash-local`). @@ -43,16 +41,29 @@ import { randomUUID } from 'node:crypto' import { availableParallelism } from 'node:os' +import * as vm from 'node:vm' import type { Context } from 'cordis' import z from 'schemastery' -import WorkflowService, { WorkflowRunId } from '@deepseek-ai/dsh-workflow' -import type { WorkflowResult, WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' +import WorkflowService, { WorkflowError, WorkflowRunId } from '@deepseek-ai/dsh-workflow' +import type { WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' +import { WorkerRun } from './host.ts' import { extractMeta } from './meta.ts' -import { WorkflowExecution, type ExecutionLimits } from './runtime.ts' +import type { WorkerInit, WorkerLimits } from './types.ts' export { extractMeta, type ExtractedScript } from './meta.ts' +export { HostToWorkerType, WorkerToHostType } from './protocol.ts' +export type { HostToWorkerMessage, HostToWorkerPayloads, WorkerToHostMessage, WorkerToHostPayloads } from './protocol.ts' export { materializeFromRealm, MaterializeError } from './realm.ts' -export { WorkflowExecution, type ExecutionLimits, type ExecutionObserver } from './runtime.ts' +export { WorkflowExecution, type ExecutionObserver } from './runtime.ts' +export { requireParentPort, runWorkerSession } from './session.ts' +export type { + ChildHandle, + ChildPort, + ChildResult, + ChildStartRequest, + WorkerInit, + WorkerLimits, +} from './types.ts' /** Plugin config (all optional — `static Config` supplies the defaults). */ export interface Config { @@ -64,12 +75,12 @@ export interface Config { maxTotalAgents?: number /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */ maxItemsPerCall?: number - /** vm timeout for the script's initial synchronous slice AND the meta-literal evaluation (default 5000 ms). */ + /** vm timeout for the initial synchronous slice (inside the worker) AND the host-side meta evaluation (default 5000 ms). */ syncTimeoutMs?: number /** * How long after a cancellation an unsettled script may keep running before - * it is abandoned and `result` force-settles `cancelled` (default 5000 ms); - * also bounds `dispose()`. + * the run force-settles `cancelled` and its worker is TERMINATED (default + * 5000 ms); also bounds `dispose()`. */ disposeGraceMs?: number } @@ -77,11 +88,27 @@ export interface Config { type ResolvedConfig = Required /** - * The vm engine service. `start()` validates the script up front (meta + - * body compile) and returns a {@link WorkflowRun} whose `result` never - * rejects; the `workflow/*` events fire around the run per the seam contract. + * Parse-check the body with the SAME wrapper the worker-side runtime + * compiles, so `start()` keeps the seam's synchronous `SCRIPT_PARSE` throw + * (the worker's own compile happens a thread away, after `start()` returned). + * One redundant parse per run, bought deliberately for the contract. */ -export class VmWorkflowEngine extends WorkflowService { +function assertBodyParses(body: string, name: string): void { + try { + // Parse only — the script object is discarded, nothing executes. + void new vm.Script(`(async () => {\n${body}\n})()`, { filename: `workflow:${name}`, lineOffset: -1 }) + } catch (error: unknown) { + throw new WorkflowError(`workflow script does not parse: ${String(error)}`, 'SCRIPT_PARSE', { cause: error }) + } +} + +/** + * The worker-thread engine service. `start()` validates the script up front + * (meta + a host-side body parse) and returns a {@link WorkflowRun} whose + * `result` never rejects; the `workflow/*` events fire around the run per + * the seam contract. + */ +export class WorkerWorkflowEngine extends WorkflowService { static inject = ['subagents'] static Config: z = z.object({ @@ -103,51 +130,56 @@ export class VmWorkflowEngine extends WorkflowService { } /** - * Parse and execute a workflow script. Throws {@link WorkflowError} - * synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot - * begin; once a run is returned, every failure resolves through - * `result.stopReason` instead. + * Parse and execute a workflow script in a fresh worker thread. Throws + * {@link WorkflowError} synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a + * script that cannot begin; once a run is returned, every failure resolves + * through `result.stopReason` instead. * @param request - the script, its `args`, the parent agent, and an * optional cancel signal. * @returns the live run (its `result` resolves when the script settles). */ start(request: WorkflowStartRequest): WorkflowRun { const { meta, body } = extractMeta(request.script, this.config.syncTimeoutMs) + assertBodyParses(body, meta.name) const id = WorkflowRunId(randomUUID()) // The event payloads and the run handle get SEPARATE meta clones: a // listener mutating its snapshot must not corrupt the holder's view. const info: WorkflowRunInfo = { id, meta: structuredClone(meta) } - const limits: ExecutionLimits = { - provider: this.config.provider, + const limits: WorkerLimits = { maxConcurrentAgents: this.config.maxConcurrentAgents === 0 ? Math.min(16, Math.max(1, availableParallelism() - 2)) : this.config.maxConcurrentAgents, maxTotalAgents: this.config.maxTotalAgents, maxItemsPerCall: this.config.maxItemsPerCall, syncTimeoutMs: this.config.syncTimeoutMs, - disposeGraceMs: this.config.disposeGraceMs, } - const execution = new WorkflowExecution( - this.ctx, + const init: WorkerInit = { meta, body, - request.parent, - request.args, - request.signal, + ...request.args !== undefined ? { args: request.args } : {}, limits, + } + const workerRun = new WorkerRun( + this.ctx, + id, + structuredClone(meta), + request.parent, + init, + this.config.provider, + this.config.disposeGraceMs, { phase: (title) => { this.emitWorkflowEvent('workflow/phase', info, title) }, log: (message) => { this.emitWorkflowEvent('workflow/log', info, message) }, agentStart: (agent) => { this.emitWorkflowEvent('workflow/agent-start', info, agent) }, agentEnd: (agent) => { this.emitWorkflowEvent('workflow/agent-end', info, agent) }, }, + request.signal, ) this.emitWorkflowEvent('workflow/start', info) - const result: Promise = execution.drive() // `workflow/end` fires as the (never-rejecting) result settles, with the // outcome DATA only — the value stays with the run's holder. - void result.then((settled) => { + void workerRun.result.then((settled) => { this.emitWorkflowEvent('workflow/end', info, { stopReason: settled.stopReason, ...settled.error !== undefined ? { error: settled.error } : {}, @@ -155,46 +187,8 @@ export class VmWorkflowEngine extends WorkflowService { }) }) - let disposed: Promise | undefined - return { - id, - meta: structuredClone(meta), - result, - cancel(reason?: string): void { - execution.cancel(reason) - }, - dispose: (): Promise => { - // Idempotent: cancel, then wait min(settle + child quiescence, grace). - // The cancel itself bounds `result` (the execution abandons a script - // still unsettled `disposeGraceMs` later), so this outer race exists - // for CHILD quiescence: a slow-disposing child must not hold dispose - // past the grace. `result` and `quiesce()` never reject, so the race - // needs no rejection handling. - disposed ??= (async () => { - execution.cancel('workflow disposed') - await Promise.race([ - (async () => { - await result - // The result settles with the SCRIPT; stray children a script - // fired without awaiting are still winding down — dispose must - // not return while they hold live resources. - await execution.quiesce() - })(), - sleep(this.config.disposeGraceMs), - ]) - })() - return disposed - }, - } + return workerRun } } -/** A plain timer sleep (the dispose grace); unref'd so it never holds the process open. */ -function sleep(ms: number): Promise { - return new Promise((resolve) => { - const timer = setTimeout(resolve, ms) - timer.unref() - }) -} - -export default VmWorkflowEngine +export default WorkerWorkflowEngine diff --git a/packages/workflow/workflow-vm/src/protocol.ts b/packages/workflow/workflow-vm/src/protocol.ts new file mode 100644 index 0000000000..293676706e --- /dev/null +++ b/packages/workflow/workflow-vm/src/protocol.ts @@ -0,0 +1,115 @@ +/** + * The host⇄worker wire protocol: one string-valued enum of message tags per + * direction, a payload map giving each tag its parameters (the single source + * of truth), and the message unions derived from them. Everything in a + * payload is plain JSON data by construction (the runtime materializes + * script values before they reach a message; the host projects seam results + * down to their JSON fields), so the structured-clone hop never meets a + * value it cannot carry. + * + * Both directions are CLOSED (engine-owned): each side switches on `type` + * and ends with `assertNever` — an unknown message is a protocol bug, never + * something to skip silently. Senders go through a generic + * `post(type, payload)` whose payload parameter is looked up from the map, + * so a tag/payload mismatch is a compile error at the call site. + * + * @module @deepseek-ai/dsh-workflow-vm/protocol + */ + +import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowResult } from '@deepseek-ai/dsh-workflow' +import type { ChildResult, ChildStartRequest } from './types.ts' + +/** Message tags the worker sends the host (the wire values are the tag strings). */ +export enum WorkerToHostType { + /** The startup handshake: the session is listening and awaits {@link HostToWorkerType.Go}. */ + Ready = 'ready', + /** Observer narration: a `phase(title)` call. */ + Phase = 'phase', + /** Observer narration: a `log(message)` call. */ + Log = 'log', + /** Observer lifecycle: one `agent()` call started a child. */ + AgentStart = 'agent-start', + /** Observer lifecycle: one `agent()` call settled. */ + AgentEnd = 'agent-end', + /** Child RPC: start a child on the host (answered by ChildStarted or ChildStartError). */ + ChildStart = 'child-start', + /** Child RPC: cancel a started child (fire-and-forget). */ + ChildCancel = 'child-cancel', + /** Child RPC: dispose a started child (answered by ChildDisposed). */ + ChildDispose = 'child-dispose', + /** The run's single terminal result. */ + Result = 'result', +} + +/** The payload each worker→host tag carries. */ +export interface WorkerToHostPayloads { + /** Ready carries nothing. */ + [WorkerToHostType.Ready]: Record + /** The phase title, verbatim. */ + [WorkerToHostType.Phase]: { title: string } + /** The logged message, verbatim. */ + [WorkerToHostType.Log]: { message: string } + /** The call's sequence number, label, phase, and child id. */ + [WorkerToHostType.AgentStart]: { info: WorkflowAgentInfo } + /** The call identity plus its outcome. */ + [WorkerToHostType.AgentEnd]: { info: WorkflowAgentEndInfo } + /** The RPC correlation id and the prompt plus validated options. */ + [WorkerToHostType.ChildStart]: { callId: number; request: ChildStartRequest } + /** The RPC correlation id and the cancel reason (undefined = unspecified). */ + [WorkerToHostType.ChildCancel]: { callId: number; reason: string | undefined } + /** The RPC correlation id of the child to dispose. */ + [WorkerToHostType.ChildDispose]: { callId: number } + /** The run's terminal outcome. */ + [WorkerToHostType.Result]: { result: WorkflowResult } +} + +/** Message tags the host sends the worker (the wire values are the tag strings). */ +export enum HostToWorkerType { + /** Releases the startup gate: run the script body. */ + Go = 'go', + /** Cancel the run: hooks start throwing and the script dies at its next await. */ + Cancel = 'cancel', + /** Child RPC reply: the start succeeded (exactly one of ChildStarted/ChildStartError per ChildStart). */ + ChildStarted = 'child-started', + /** Child RPC reply: the start was refused or threw. */ + ChildStartError = 'child-start-error', + /** Child RPC: a started child's result RESOLVED (its JSON projection). */ + ChildSettled = 'child-settled', + /** Child RPC: a started child's result REJECTED (an infrastructure fault, rendered). */ + ChildFailed = 'child-failed', + /** Child RPC reply: a requested disposal completed. */ + ChildDisposed = 'child-disposed', +} + +/** The payload each host→worker tag carries. */ +export interface HostToWorkerPayloads { + /** Go carries nothing. */ + [HostToWorkerType.Go]: Record + /** The cancel reason, canonical for the whole run. */ + [HostToWorkerType.Cancel]: { reason: string } + /** The RPC correlation id and the child agent's id (minted by the subagent seam). */ + [HostToWorkerType.ChildStarted]: { callId: number; childId: string } + /** The RPC correlation id and the rendered start failure. */ + [HostToWorkerType.ChildStartError]: { callId: number; rendered: string } + /** The RPC correlation id and the child's terminal result projection. */ + [HostToWorkerType.ChildSettled]: { callId: number; result: ChildResult } + /** The RPC correlation id and the rendered infrastructure fault. */ + [HostToWorkerType.ChildFailed]: { callId: number; rendered: string } + /** The RPC correlation id of the completed disposal. */ + [HostToWorkerType.ChildDisposed]: { callId: number } +} + +/** + * One worker→host message of tag `T`; unparameterized, the closed union over + * every tag (a discriminated union — `switch` on `type` narrows). + */ +export type WorkerToHostMessage = + { [K in T]: { type: K } & WorkerToHostPayloads[K] }[T] + +/** + * One host→worker message of tag `T`; unparameterized, the closed union over + * every tag (a discriminated union — `switch` on `type` narrows). + */ +export type HostToWorkerMessage = + { [K in T]: { type: K } & HostToWorkerPayloads[K] }[T] + diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-vm/src/realm.ts index f5a2665626..017de76069 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-vm/src/realm.ts @@ -1,7 +1,10 @@ /** - * The vm engine's value boundary: copy script-realm values into plain host - * JSON data — loud about everything JSON cannot carry — and render thrown - * script values to failure text. + * The engine's value boundary: copy script-realm values into plain JSON data + * — loud about everything JSON cannot carry — and render thrown script + * values to failure text. The script runs in a vm context INSIDE the worker + * thread, so "host" here means the worker-side JavaScript around that + * context; everything that later crosses the thread boundary is JSON by this + * walk, which is what makes the postMessage hop total. * * TRUST PREMISE (everything in this module hangs on it): workflow scripts are * MODEL-WRITTEN, the same trust level as the model's existing bash access, so @@ -13,18 +16,16 @@ * properties ordinarily (a getter runs, and whatever it returns is what * crosses), {@link renderThrown} reads `stack`/`message`/`String()` directly, * and a proxy is walked through its traps. A hostile script gains nothing - * worth defending here — it can already occupy the event loop forever with a - * synchronous spin past the first await (the engine's documented, accepted - * limitation) — so host-side hostile-value containment would be cost without - * a threat model; genuine hardening is an ENGINE SWAP (worker/isolated-vm, - * where the boundary is serialization by construction), not incremental - * defenses here. + * worth defending here — the vm context inside the worker is escapable by + * construction, so hostile-value containment would be cost without a threat + * model (what the worker thread DOES buy is that a spin occupies the + * worker's loop, not the host's, and termination is real). * * The host→realm direction needs no machinery at all: hooks hand the script - * plain host values, host prototypes included — the script is trusted. One - * consequence is documented in the engine README: an error thrown by a hook - * is a HOST error, so an in-script `instanceof Error` check is false; read - * `name`/`code`/`message` instead. + * plain values of the worker realm, prototypes included — the script is + * trusted. One consequence is documented in the engine README: an error + * thrown by a hook is built OUTSIDE the script's vm context, so an in-script + * `instanceof Error` check is false; read `name`/`code`/`message` instead. * * @module @deepseek-ai/dsh-workflow-vm/realm */ diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts index c4e5d1c651..3005520fa0 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-vm/src/runtime.ts @@ -1,40 +1,44 @@ /** - * Per-run execution state for the vm workflow engine: the script context and - * its injected hooks (`agent`/`parallel`/`pipeline`/`phase`/`log`/`args`), the - * concurrency semaphore and caps, cancellation, and the drive loop that turns - * a script settlement into a {@link WorkflowResult}. + * Per-run execution state for the engine's THREAD side: the script's vm + * context and its injected hooks (`agent`/`parallel`/`pipeline`/`phase`/ + * `log`/`args`), the concurrency semaphore and caps, cancellation, and the + * drive loop that turns a script settlement into a {@link WorkflowResult}. + * Children are started by RPC to the host through a {@link ChildPort}, so + * this module never touches a cordis context — it runs inside the worker + * thread. * * Value boundary (the trust premise lives in ./realm.ts): values ENTERING the - * host from the script (hook options, schemas, the return value) are - * materialized by `materializeFromRealm` — a plain walk that rejects loud - * everything JSON cannot carry. Values ENTERING the realm (`args`, `agent()` - * results, hook promises and their failures, combinator arrays) are handed - * over DIRECTLY as host values: the script is model-written and trusted, so - * host prototypes are not a leak. `args` is host-side `structuredClone`d once - * at start so a script scribbling on it cannot mutate the caller's object — - * that is a benign-bug guard, not isolation. Realm functions (pipeline - * stages, parallel thunks) are called, not materialized — their values stay - * realm-side until they cross through a hook or the final return. + * worker-side host code from the script (hook options, schemas, the return + * value) are materialized by `materializeFromRealm` — a plain walk that + * rejects loud everything JSON cannot carry, which also makes every value + * safe for the later postMessage hop. Values ENTERING the realm (`args`, + * `agent()` results, hook promises and their failures, combinator arrays) are + * handed over DIRECTLY as worker-realm values: the script is model-written + * and trusted, so outer prototypes are not a leak. `args` is cloned once at + * start so a script scribbling on it cannot mutate the session's init object + * (a benign-bug guard; the postMessage clone already isolated the caller). * * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments, - * unsupported options/schemas, tripped caps, seam start failures and result - * rejections, cancellation) ALWAYS propagate through `parallel`/`pipeline` — - * recognized by host `instanceof`, which a script cannot forge — and the - * per-item `null` is reserved for child-run failures and ordinary in-stage - * script errors. - * Every hook-returned promise gets a no-op rejection consumer attached, so a - * script that drops a promise (fires an `agent()` without awaiting it) cannot - * surface an unhandled rejection when cancellation rejects it — the app boot - * layer exits the process on unhandled rejections. + * unsupported options/schemas, tripped caps, host start refusals and child + * result rejections, cancellation) ALWAYS propagate through + * `parallel`/`pipeline` — recognized by `instanceof` against this realm's + * class, which a script inside the vm context cannot forge — and the per-item + * `null` is reserved for child-run failures and ordinary in-stage script + * errors. Every hook-returned promise gets a no-op rejection consumer, so a + * dropped promise cannot surface an unhandled rejection (which would kill the + * worker and read as an engine fault). + * + * There is deliberately NO worker-side abandon channel: a script that never + * settles after a cancel simply never posts a result, and the HOST enforces + * the settles-within-grace guarantee by force-settling `cancelled` and + * terminating the worker — the real kill an in-process engine could not have. * * @module @deepseek-ai/dsh-workflow-vm/runtime */ import * as vm from 'node:vm' -import type { Context } from 'cordis' +import { AgentId } from '@deepseek-ai/dsh-agent' import type { ContentBlock } from '@deepseek-ai/dsh-llm' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type {} from '@deepseek-ai/dsh-subagent' import { assertSupportedOutputSchema, OutputSchemaError } from '@deepseek-ai/dsh-tools' import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' import { isFatalWorkflowError, WorkflowError } from '@deepseek-ai/dsh-workflow' @@ -45,24 +49,9 @@ import type { WorkflowResult, } from '@deepseek-ai/dsh-workflow' import { materializeFromRealm, MaterializeError, renderThrown } from './realm.ts' +import type { ChildHandle, ChildPort, WorkerLimits } from './types.ts' -/** The per-run knobs the engine resolves from its Config. */ -export interface ExecutionLimits { - /** The `ctx.subagents` provider name to start children on. */ - provider: string - /** Concurrent `agent()` ceiling (already auto-resolved; ≥ 1). */ - maxConcurrentAgents: number - /** Total `agent()` calls per run (the runaway-loop backstop). */ - maxTotalAgents: number - /** Items accepted by one `parallel()`/`pipeline()` call. */ - maxItemsPerCall: number - /** vm timeout for the script's initial synchronous slice. */ - syncTimeoutMs: number - /** How long after `cancel()` a still-unsettled script is abandoned (result force-settles `cancelled`). */ - disposeGraceMs: number -} - -/** The engine-side observers the execution reports progress through. */ +/** The observers the execution reports progress through (the session posts them to the host). */ export interface ExecutionObserver { phase(title: string): void log(message: string): void @@ -91,9 +80,9 @@ function defaultLabel(prompt: string): string { } /** - * One live script execution. Constructed per run by the engine; `drive()` is - * called exactly once and NEVER rejects — every failure becomes a - * {@link WorkflowResult} with a non-`completed` stop reason. + * One live script execution inside the worker. Constructed per run by the + * session; `drive()` is called exactly once and NEVER rejects — every failure + * becomes a {@link WorkflowResult} with a non-`completed` stop reason. */ export class WorkflowExecution { /** 1-based count of `agent()` calls started (the `agentsStarted` result field). */ @@ -106,36 +95,19 @@ export class WorkflowExecution { private currentPhase: string | undefined private readonly context: vm.Context private readonly compiled: vm.Script - /** Every live `agent()` call promise — awaited or stray — for {@link quiesce}. */ - private readonly inFlightAgents = new Set>() - /** Fires {@link abandoned}; assigned by the promise executor at field initialization. */ - private declareAbandoned!: () => void - private abandonTimer: NodeJS.Timeout | undefined - /** - * Rejects `disposeGraceMs` after {@link cancel} if the script has not - * settled by then. `drive()` races the script against it, so `result` - * ALWAYS settles within the grace of a cancellation — even when the script - * is parked on a promise no hook owns (`await new Promise(() => {})`), which - * cancellation cannot reject. Without this, a consumer awaiting `result` - * before disposing (the tool's shape) would hang forever on such a script, - * wedging its caller past any abort. - */ - private readonly abandoned = new Promise((_, reject) => { - this.declareAbandoned = () => { reject(new WorkflowError('workflow script abandoned after the cancellation grace', 'CANCELLED')) } - }) constructor( - private readonly ctx: Context, meta: WorkflowMeta, body: string, - private readonly parent: Agent, args: unknown, - signal: AbortSignal | undefined, - private readonly limits: ExecutionLimits, + private readonly limits: WorkerLimits, private readonly observer: ExecutionObserver, + private readonly children: ChildPort, ) { // Compile FIRST: a body syntax error must throw out of the constructor - // (the engine maps it to SCRIPT_PARSE) before any realm state exists. + // before any realm state exists. The host pre-parses the identical + // wrapper, so under one Node version this throw is unreachable in + // production — the session still maps it to an error result defensively. // lineOffset compensates for the wrapper line, so stack traces carry the // script's own line numbers (the meta statement was blanked, not removed). try { @@ -148,20 +120,17 @@ export class WorkflowExecution { } this.context = vm.createContext({}, { name: `workflow:${meta.name}` }) - // A run that settles without ever being abandoned leaves `abandoned` - // permanently pending or rejecting into the void — consume it so a late - // grace timer cannot surface an unhandled rejection. - void this.contain(this.abandoned) const globals: Record = { - agent: (prompt: unknown, opts?: unknown) => this.contain(this.track(this.agent(prompt, opts))), + agent: (prompt: unknown, opts?: unknown) => this.contain(this.agent(prompt, opts)), parallel: (thunks: unknown) => this.contain(this.parallel(thunks)), pipeline: (items: unknown, ...stages: unknown[]) => this.contain(this.pipeline(items, stages)), phase: (title: unknown) => { this.phase(title) }, log: (message: unknown) => { this.log(message) }, - // Host-side clone: a script scribbling on args must not mutate the - // caller's object (a benign-bug guard; args is plain JSON by the seam - // contract, so structuredClone is total here and throws loud otherwise). + // Cloned once: a script scribbling on args must not mutate the + // session's init object (a benign-bug guard; args is plain JSON by the + // seam contract and already crossed one structured clone as workerData, + // so this clone is total). args: args === undefined ? undefined : structuredClone(args), } for (const [key, value] of Object.entries(globals)) { @@ -169,18 +138,12 @@ export class WorkflowExecution { // a script overwriting its own hooks only sabotages itself. ;(this.context as Record)[key] = typeof value === 'function' ? Object.freeze(value) : value } - - if (signal?.aborted) { - this.cancel('workflow start signal already aborted') - } else { - signal?.addEventListener('abort', () => { this.cancel('workflow signal aborted') }, { once: true }) - } } /** * Whether the run has been cancelled. A METHOD, not an inline property - * read: `cancel()` mutates `cancelReason` concurrently (a signal listener, - * a raced dispose), and an inline read after an `await` gets narrowed by + * read: `cancel()` mutates `cancelReason` concurrently (the session's + * message handler), and an inline read after an `await` gets narrowed by * control flow into an always-false comparison. */ private isCancelled(): boolean { @@ -199,45 +162,41 @@ export class WorkflowExecution { } /** - * Cancel the run: children abort (the shared signal), waiting `agent()` - * slots reject, and every future hook call throws `CANCELLED` — the script - * dies at its next await. A script that STILL has not settled after - * `disposeGraceMs` (parked on a promise no hook owns) is abandoned so - * `result` settles regardless (see {@link abandoned}). Idempotent; the - * first reason wins. + * Cancel the run: in-flight children get a cancel RPC (the shared abort + * fanout), waiting `agent()` slots reject, and every future hook call + * throws `CANCELLED` — the script dies at its next await. A script that + * never settles anyway (parked on a promise no hook owns) is the HOST's + * problem: its grace timer force-settles the run and terminates the + * worker. Idempotent; the first reason wins. * @param reason - human-readable cause, carried on the CANCELLED error and - * into child `run.cancel()` calls (default `'workflow cancelled'`). + * into child cancel RPCs. Required: every caller (the session's cancel + * message, drive()'s settle-reap) has a concrete reason. */ - cancel(reason?: string): void { + cancel(reason: string): void { if (this.cancelReason !== undefined) return - this.cancelReason = reason ?? 'workflow cancelled' + this.cancelReason = reason this.cancelError = new WorkflowError(`workflow run cancelled: ${this.cancelReason}`, 'CANCELLED') this.controller.abort(this.cancelReason) for (const waiter of this.slotWaiters.splice(0)) waiter.reject(this.cancelledError()) - this.abandonTimer = setTimeout(() => { this.declareAbandoned() }, this.limits.disposeGraceMs) - // unref'd: an armed grace timer must never hold the process open. - this.abandonTimer.unref() } /** * Run the script to settlement. Resolves — never rejects — with the run's * {@link WorkflowResult}: the materialized return value on `completed`, the * failure message on `error`, and `cancelled` when the script died of - * cancellation (or outlived its post-cancel grace and was abandoned — see - * {@link abandoned}). After settlement, any stray children a script fired - * without awaiting are aborted (their `agent()` wrappers dispose them). + * cancellation. After settlement, any stray children a script fired without + * awaiting are cancelled (their `agent()` wrappers dispose them via RPC). * @returns the settled outcome — this promise NEVER rejects (the seam's * `result`-never-rejects contract); every failure maps to a variant. */ async drive(): Promise { try { - // Cancelled before the body ever ran (an already-aborted start signal): - // the script must not execute at all, let alone report `completed`. + // Cancelled before the body ever ran (an already-aborted start signal, + // relayed by the host before its `go`): the script must not execute at + // all, let alone report `completed`. if (this.isCancelled()) throw this.cancelledError() const scriptPromise = this.compiled.runInContext(this.context, { timeout: this.limits.syncTimeoutMs }) as Promise - // The race is the result-settles-after-cancel guarantee: a parked - // script loses to the abandon channel once the grace expires. - const raw: unknown = await Promise.race([this.contain(Promise.resolve(scriptPromise)), this.abandoned]) + const raw: unknown = await this.contain(Promise.resolve(scriptPromise)) // Cancelled while the body ran: a script that settled without touching // another hook (or without any) must still report `cancelled` — the // holder asked for cancellation and `completed` would be a lie. @@ -250,59 +209,30 @@ export class WorkflowExecution { if (this.isCancelled()) { return { value: null, stopReason: 'cancelled', error: this.cancelledError().message, agentsStarted: this.started } } - // renderThrown is total (host- and realm-thrown values alike), so this - // arm cannot throw — drive() resolving is the `result` never-rejects - // seam contract. + // renderThrown is total (thrown values of any realm), so this arm + // cannot throw — drive() resolving is the `result` never-rejects seam + // contract. return { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: this.started } } finally { // Reap strays: a script that fired agent() calls without awaiting them - // leaves live children behind after settlement — abort them all. (The + // leaves live children behind after settlement — cancel them all. (The // per-call wrappers dispose each child; the contain() consumer keeps // their rejections from going unhandled.) if (this.cancelReason === undefined) this.cancel('workflow settled') - // drive() settling means nothing is left to abandon — including the - // timer the self-cancel above just armed (cancel() always arms it, so - // it is never undefined here; clearTimeout tolerates undefined anyway). - clearTimeout(this.abandonTimer) } } /** * Attach a no-op rejection consumer WITHOUT changing what the caller * receives: if the script drops the promise (no await), cancellation cannot - * become an unhandled rejection (the app boot layer exits the process on - * those); if the script does await it, it still observes the rejection. + * become an unhandled rejection (which would kill the worker thread); if + * the script does await it, it still observes the rejection. */ private contain(promise: Promise): Promise { promise.catch(() => { /* consumed: see method contract — a dropped hook promise must not surface an unhandled rejection */ }) return promise } - /** - * Register one `agent()` call promise for {@link quiesce} tracking; the - * entry drops when the call fully settles (which is AFTER its child's - * `dispose()` — the call wrapper disposes in its `finally`). - */ - private track(promise: Promise): Promise { - this.inFlightAgents.add(promise) - const drop = (): void => { this.inFlightAgents.delete(promise) } - promise.then(drop, drop) - return promise - } - - /** - * Settles once every `agent()` call — awaited or stray — has fully settled, - * INCLUDING each child's `dispose()`. The reap in {@link drive}'s finally - * aborts strays; this is the wait for those aborts to reach quiescence, so - * the engine's `dispose()` cannot return while a child is still winding - * down. Never rejects (the tracked promises' rejections are contained). - */ - async quiesce(): Promise { - while (this.inFlightAgents.size > 0) { - await Promise.allSettled([...this.inFlightAgents]) - } - } - private cancelledError(): WorkflowError { // cancel() arms cancelError before any caller can observe isCancelled() // === true; the fallback guards the type, not a reachable path. @@ -375,28 +305,37 @@ export class WorkflowExecution { // Re-check after the acquire: the await yields at least one microtask // tick even when a slot is free, and a queued waiter resumes a tick // after its release — a cancel() landing in either window must not - // start a child (it would carry an ALREADY-aborted signal, which a - // provider subscribing only to future abort events would never see). + // reach the host (which would refuse anyway, but the refusal reads as + // a start failure rather than the cancellation it is). this.throwIfCancelled() - let run + let run: ChildHandle try { - run = this.ctx.subagents.start(this.limits.provider, { - prompt: [{ type: 'text', text: rawPrompt }], - parent: this.parent, - signal: this.controller.signal, - ...opts.schema !== undefined ? { outputSchema: opts.schema } : {}, - ...opts.model !== undefined ? { agentOptions: { model: opts.model } } : {}, + run = await this.children.startAgent({ + prompt: rawPrompt, + ...opts.schema !== undefined ? { schema: opts.schema } : {}, + ...opts.model !== undefined ? { model: opts.model } : {}, }) } catch (error: unknown) { - throw new WorkflowError(`agent() could not start a child on provider "${this.limits.provider}": ${String(error)}`, 'AGENT_START', { cause: error }) + // The host refuses starts once the run is cancelled — a refusal that + // races our own cancel state must read as the cancellation it is, + // not as a broken seam. + if (this.isCancelled()) throw this.cancelledError() + throw new WorkflowError(`agent() could not start a child: ${renderThrown(error)}`, 'AGENT_START', { cause: error }) } - const info: WorkflowAgentInfo = { seq, label, ...phase !== undefined ? { phase } : {}, childId: run.id } + // The start round-trip yields to the event loop, so a cancel CAN land + // between the host starting the child and this continuation running — + // wind the fresh child down instead of leaving it live behind a dead + // script. + if (this.isCancelled()) { + run.cancel(this.cancelReason) + await run.dispose() + throw this.cancelledError() + } + const info: WorkflowAgentInfo = { seq, label, ...phase !== undefined ? { phase } : {}, childId: AgentId(run.id) } this.observer.agentStart(info) - // Cancellation bridges to run.cancel() as well as the request signal: - // the seam leaves a provider free to honor either channel, so the - // consumer must drive both. The signal cannot be aborted yet (the block - // since the post-acquire check is synchronous), so the listener always - // arms; `once` plus the finally removal keep it leak-free. + // Cancellation reaches the child through an explicit cancel RPC per + // child (the host also aborts its own per-run signal, but the seam + // leaves a provider free to honor either channel, so both are driven). const onAbort = (): void => { run.cancel(this.cancelReason) } this.controller.signal.addEventListener('abort', onAbort, { once: true }) try { @@ -404,8 +343,8 @@ export class WorkflowExecution { try { result = await run.result } catch (error: unknown) { - // The seam allows `result` to reject for an INFRASTRUCTURE fault — - // distinct from a child that failed and resolved. Pair the + // A rejected child result is an INFRASTRUCTURE fault relayed by the + // host — distinct from a child that failed and resolved. Pair the // lifecycle before propagating, and propagate FATAL: an ordinary // throw would dissolve to a per-item null inside the combinators, // and a broken provider must not read as a failed child. @@ -510,9 +449,10 @@ export class WorkflowExecution { try { return await thunk() } catch (error: unknown) { - // Hook failures are host WorkflowErrors; a fatal one is recognized by - // host `instanceof` — a script-built object can never pass it, so - // fatality cannot be forged (nor accidentally dissolved). + // Hook failures are WorkflowErrors built OUTSIDE the script's realm; + // fatality is recognized by `instanceof` against this realm's class — + // a script-built object can never pass it, so fatality cannot be + // forged (nor accidentally dissolved). if (isFatalWorkflowError(error)) throw error return null } @@ -544,8 +484,8 @@ export class WorkflowExecution { return value } catch (error: unknown) { // An ordinary stage throw drops the ITEM to null and skips its - // remaining stages; a fatal host WorkflowError (see parallel()) kills - // the whole script. + // remaining stages; a fatal WorkflowError (see parallel()) kills the + // whole script. if (isFatalWorkflowError(error)) throw error return null } diff --git a/packages/workflow/workflow-vm/src/session.ts b/packages/workflow/workflow-vm/src/session.ts new file mode 100644 index 0000000000..131f760ff9 --- /dev/null +++ b/packages/workflow/workflow-vm/src/session.ts @@ -0,0 +1,210 @@ +/** + * The worker-side half of the engine: {@link runWorkerSession} wires one + * MessagePort to one {@link WorkflowExecution} — hook progress and child + * starts go out as messages, run control and child lifecycle come back in — + * and posts the run's terminal result exactly once. Deliberately separated + * from the thread bootstrap (./worker.ts): the whole session is drivable + * in-process over a `MessageChannel`, which is where its unit coverage lives + * (code inside a real Worker is invisible to the main process's coverage). + * + * Startup handshake: the session posts `ready` and runs the script only + * after the host's `go` — without it, a cancellation racing the worker's + * boot could arrive AFTER the script's initial synchronous slice already + * ran, and a run cancelled before start must not execute the body at all. + * A `cancel` arriving instead of `go` still releases the gate: `drive()` + * sees the cancelled state and settles without running the body. + * + * @module @deepseek-ai/dsh-workflow-vm/session + */ + +import type { MessagePort } from 'node:worker_threads' +import { assertNever } from '@deepseek-ai/dsh-llm' +import { HostToWorkerType, WorkerToHostType } from './protocol.ts' +import type { HostToWorkerMessage, WorkerToHostPayloads } from './protocol.ts' +import { renderThrown } from './realm.ts' +import { WorkflowExecution } from './runtime.ts' +import type { ExecutionObserver } from './runtime.ts' +import type { + ChildHandle, + ChildPort, + ChildResult, + ChildStartRequest, + WorkerInit, +} from './types.ts' + +/** The book-keeping for one in-flight child RPC (keyed by callId). */ +interface PendingChild { + started: PromiseWithResolvers + settled: PromiseWithResolvers + disposed: PromiseWithResolvers +} + +/** The typed post half of the port: each tag pairs with ITS payload from the map (a mismatch is a compile error at the call site). */ +type Post = (type: T, payload: WorkerToHostPayloads[T]) => void + +/** + * The worker-side handle for one started child agent ({@link ChildHandle}): + * every member is an RPC to the host keyed by this call's `callId`, resolved + * by the session's message handler through the bridge's pending entry. + */ +class RpcChildHandle implements ChildHandle { + readonly result: Promise + + constructor( + private readonly post: Post, + private readonly callId: number, + private readonly entry: PendingChild, + readonly id: string, + ) { + this.result = entry.settled.promise + } + + cancel(reason?: string): void { + this.post(WorkerToHostType.ChildCancel, { callId: this.callId, reason }) + } + + dispose(): Promise { + this.post(WorkerToHostType.ChildDispose, { callId: this.callId }) + return this.entry.disposed.promise + } +} + +/** + * The worker-side child-RPC bridge ({@link ChildPort}): allocates callIds, + * posts the start/cancel/dispose RPCs, and owns the per-call pending + * book-keeping the session's message handler settles via the `onChild*` + * entry points. + */ +class ChildRpcBridge implements ChildPort { + private nextCallId = 0 + private readonly pending = new Map() + + constructor(private readonly post: Post) {} + + async startAgent(request: ChildStartRequest): Promise { + this.nextCallId += 1 + const callId = this.nextCallId + const entry: PendingChild = { + started: Promise.withResolvers(), + settled: Promise.withResolvers(), + disposed: Promise.withResolvers(), + } + // Containment: when the start is refused (or the run torn down) the + // settled promise may never gain a consumer — it must not surface as an + // unhandled rejection and kill the worker. + entry.settled.promise.catch(() => { /* consumed: unconsumed child settlement after a refused start */ }) + this.pending.set(callId, entry) + this.post(WorkerToHostType.ChildStart, { callId, request }) + const childId = await entry.started.promise + return new RpcChildHandle(this.post, callId, entry, childId) + } + + /** The host started the child; releases the `startAgent` await. */ + onChildStarted(callId: number, childId: string): void { + this.pending.get(callId)?.started.resolve(childId) + } + + /** The host refused the start; `startAgent` rejects with the rendered cause. */ + onChildStartError(callId: number, rendered: string): void { + this.pending.get(callId)?.started.reject(new Error(rendered)) + } + + /** The child's terminal result arrived. */ + onChildSettled(callId: number, result: ChildResult): void { + this.pending.get(callId)?.settled.resolve(result) + } + + /** The child's `result` rejected host-side (an infrastructure fault, relayed as fatal). */ + onChildFailed(callId: number, rendered: string): void { + this.pending.get(callId)?.settled.reject(new Error(rendered)) + } + + /** The host acked the dispose; the call's book-keeping is complete. */ + onChildDisposed(callId: number): void { + const entry = this.pending.get(callId) + this.pending.delete(callId) + entry?.disposed.resolve() + } +} + +/** + * Narrow the nullable `parentPort` the bootstrap reads from + * `node:worker_threads`. + * @param port - `parentPort` as imported (null on the main thread). + * @returns the port, non-null. + */ +export function requireParentPort(port: MessagePort | null): MessagePort { + if (port === null) throw new Error('the workflow worker entry must be loaded inside a worker thread (no parentPort)') + return port +} + +/** + * Run one workflow script to settlement against `port`, posting the terminal + * result message exactly once; resolves after that post (stray children may + * still be winding down through the port — the host owns their teardown and + * ultimately terminates the thread). Never rejects: a constructor failure + * (unparseable body — host pre-parse makes this a Node-version-skew signal) + * is reported as an `error` result rather than dying without a result. + * @param port - the channel to the host (the real `parentPort`, or one side + * of an in-process `MessageChannel` in tests). + * @param init - the run payload the host provided as `workerData`. + */ +export async function runWorkerSession(port: MessagePort, init: WorkerInit): Promise { + const post: Post = (type, payload) => { + port.postMessage({ type, ...payload }) + } + const children = new ChildRpcBridge(post) + + const observer: ExecutionObserver = { + phase: (title) => { post(WorkerToHostType.Phase, { title }) }, + log: (message) => { post(WorkerToHostType.Log, { message }) }, + agentStart: (info) => { post(WorkerToHostType.AgentStart, { info }) }, + agentEnd: (info) => { post(WorkerToHostType.AgentEnd, { info }) }, + } + + let execution: WorkflowExecution + try { + execution = new WorkflowExecution(init.meta, init.body, init.args, init.limits, observer, children) + } catch (error: unknown) { + post(WorkerToHostType.Result, { result: { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: 0 } }) + return + } + + const gate = Promise.withResolvers() + port.on('message', (message: HostToWorkerMessage) => { + switch (message.type) { + case HostToWorkerType.Go: + gate.resolve() + break + case HostToWorkerType.Cancel: + execution.cancel(message.reason) + // A cancel doubles as the gate release: drive() checks the cancelled + // state before running the body, so the script never executes. + gate.resolve() + break + case HostToWorkerType.ChildStarted: + children.onChildStarted(message.callId, message.childId) + break + case HostToWorkerType.ChildStartError: + children.onChildStartError(message.callId, message.rendered) + break + case HostToWorkerType.ChildSettled: + children.onChildSettled(message.callId, message.result) + break + case HostToWorkerType.ChildFailed: + children.onChildFailed(message.callId, message.rendered) + break + case HostToWorkerType.ChildDisposed: + children.onChildDisposed(message.callId) + break + /* v8 ignore next 2 -- closed engine-owned union; the arm only makes adding a message type a compile error */ + default: + assertNever(message, 'host-to-worker message') + } + }) + + post(WorkerToHostType.Ready, {}) + await gate.promise + const result = await execution.drive() + post(WorkerToHostType.Result, { result }) +} diff --git a/packages/workflow/workflow-vm/src/types.ts b/packages/workflow/workflow-vm/src/types.ts new file mode 100644 index 0000000000..c87fc4668c --- /dev/null +++ b/packages/workflow/workflow-vm/src/types.ts @@ -0,0 +1,97 @@ +/** + * Non-protocol wire vocabulary for the worker-thread engine: the `workerData` init + * payload and the child-port interfaces the worker-side runtime consumes. + * The host⇄worker MESSAGE protocol lives in ./protocol.ts; everything here + * that a message transports (`ChildStartRequest`, `ChildResult`) is plain + * JSON data by construction, so the structured-clone hop never meets a value + * it cannot carry. Types only, per the package convention. + * + * @module @deepseek-ai/dsh-workflow-vm/types + */ + +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools' +import type { WorkflowMeta } from '@deepseek-ai/dsh-workflow' + +/** + * The per-run limits the worker-side runtime enforces. The host keeps the + * knobs only it can act on (`provider`, `disposeGraceMs`). + */ +export interface WorkerLimits { + /** Concurrent `agent()` ceiling (already auto-resolved; ≥ 1). */ + maxConcurrentAgents: number + /** Total `agent()` calls per run (the runaway-loop backstop). */ + maxTotalAgents: number + /** Items accepted by one `parallel()`/`pipeline()` call. */ + maxItemsPerCall: number + /** vm timeout for the script's initial synchronous slice (inside the worker). */ + syncTimeoutMs: number +} + +/** The `workerData` payload one run is initialized with (host → worker, once, at spawn). */ +export interface WorkerInit { + /** The validated meta block (extracted host-side). */ + meta: WorkflowMeta + /** The script body with the meta statement blanked (host-side `extractMeta`). */ + body: string + /** The run's `args` value; the workerData structured clone is the copy that isolates the caller. */ + args?: unknown + /** The worker-enforced limits. */ + limits: WorkerLimits +} + +/** What the worker asks the host to start for one `agent()` call (options already validated worker-side). */ +export interface ChildStartRequest { + /** The child's prompt text. */ + prompt: string + /** The structured-output schema, if the call passed one (already subset-checked). */ + schema?: StructuredOutputSchema + /** The per-child model override, if the call passed one. */ + model?: string +} + +/** + * The JSON projection of a child's `SubagentResult` crossing the port. The + * seam's `stopReason` union is merge-extensible, so it degrades to `string` + * on the wire — the runtime only ever branches on `'completed'`. + */ +export interface ChildResult { + /** The child's final assistant output blocks. */ + output: ContentBlock[] + /** The structured value, present iff the request carried a schema AND the provider honored it. */ + structured?: unknown + /** Why the child run ended (`'completed'` is the only value the runtime branches on). */ + stopReason: string +} + +/** + * The worker-side handle for one started child — the RPC mirror of the + * subagent seam's run handle, reduced to what the runtime consumes. + */ +export interface ChildHandle { + /** The child agent's id (minted host-side by the subagent seam). */ + readonly id: string + /** + * Resolves with the child's terminal {@link ChildResult}; REJECTS only when + * the host reports an infrastructure fault (`child-failed`) — a child that + * failed for its own reasons resolves with a non-`completed` stop reason. + */ + readonly result: Promise + /** Ask the host to cancel the child (fire-and-forget). */ + cancel(reason?: string): void + /** Ask the host to dispose the child; resolves on the host's ack. */ + dispose(): Promise +} + +/** + * The worker-side port the runtime starts child agents through — the seam + * that lets the execution core stay ignorant of the thread boundary. + */ +export interface ChildPort { + /** + * Start one child agent on the host (the `agent()` hook's start half). + * @param request - the prompt and validated options. + * @returns the child handle; rejects when the host refuses the start. + */ + startAgent(request: ChildStartRequest): Promise +} diff --git a/packages/workflow/workflow-vm/src/worker.ts b/packages/workflow/workflow-vm/src/worker.ts new file mode 100644 index 0000000000..3b20600d7d --- /dev/null +++ b/packages/workflow/workflow-vm/src/worker.ts @@ -0,0 +1,18 @@ +/** + * The worker-thread entry the engine spawns: bootstrap ./session.ts on the + * real `parentPort`. Deliberately a single statement — every piece of logic + * lives in `runWorkerSession`, which the unit suite drives in-process over a + * `MessageChannel` (code inside a real Worker is invisible to main-process + * coverage); loading this module on the main thread throws via + * `requireParentPort`, which is how the suite covers the file itself. + * + * @module @deepseek-ai/dsh-workflow-vm/worker + */ + +import { parentPort, workerData } from 'node:worker_threads' +import { requireParentPort, runWorkerSession } from './session.ts' +import type { WorkerInit } from './types.ts' + +// workerData is `any` at the node:worker_threads boundary; the engine is the +// only spawner and always provides a WorkerInit. +void runWorkerSession(requireParentPort(parentPort), workerData as WorkerInit) diff --git a/packages/workflow/workflow-vm/tests/built-worker.e2e.ts b/packages/workflow/workflow-vm/tests/built-worker.e2e.ts new file mode 100644 index 0000000000..9bdd3865bb --- /dev/null +++ b/packages/workflow/workflow-vm/tests/built-worker.e2e.ts @@ -0,0 +1,56 @@ +import { existsSync } from 'node:fs' +import { rm, writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { execFile } from 'node:child_process' +import { promisify } from 'node:util' +import { fileURLToPath } from 'node:url' +import { describe, expect, it } from 'vitest' + +const packageRoot = fileURLToPath(new URL('..', import.meta.url)) +const builtIndex = join(packageRoot, 'lib', 'index.js') +const builtWorker = join(packageRoot, 'lib', 'worker.js') +const run = promisify(execFile) + +/** + * The BUILT-output guard for the worker entry: every other suite runs + * unbuilt (src/ + tsx), so nothing else proves that `lib/index.js` resolves + * its sibling `lib/worker.js` and that the bundle boots a worker under plain + * node (no tsx loader). Keyless — a zero-agent script needs no provider — + * and self-skips until `pnpm run build` has produced the bundles. + */ +describe.skipIf(!existsSync(builtIndex) || !existsSync(builtWorker))('built worker entry (lib/worker.js)', () => { + it('the built engine spawns its built worker under plain node and completes a run', async () => { + // ESM resolves bare specifiers from the IMPORTING FILE's location, so the + // driver must live inside the package for its node_modules to apply — a + // temp-named file at the package root, removed on the way out. + const driver = join(packageRoot, `.built-worker-driver-${process.pid}.mjs`) + try { + await writeFile(driver, ` +import { Context } from 'cordis' +import SubagentService from '@deepseek-ai/dsh-subagent' +import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' + +const ctx = new Context() +await ctx.plugin(SubagentService) +await ctx.plugin(WorkerWorkflowEngine, {}) +const run = ctx.workflows.start({ + script: "export const meta = { name: 'built-smoke', description: 'built worker smoke' }\\nreturn 6 * 7", + // A zero-agent script never touches the provider, so a bare id suffices. + parent: { id: 'built-smoke-parent', options: {} }, +}) +const result = await run.result +await run.dispose() +if (result.stopReason !== 'completed' || result.value !== 42) { + console.error('unexpected result: ' + JSON.stringify(result)) + process.exit(1) +} +console.log('built-worker-smoke-ok') +`, 'utf8') + // Plain node — no tsx loader anywhere; the bundle must stand on its own. + const { stdout } = await run(process.execPath, [driver], { cwd: packageRoot, timeout: 60_000 }) + expect(stdout).toContain('built-worker-smoke-ok') + } finally { + await rm(driver, { force: true }) + } + }, 120_000) +}) diff --git a/packages/workflow/workflow-vm/tests/integration.spec.ts b/packages/workflow/workflow-vm/tests/integration.spec.ts index 3572131a8a..e53ea518bc 100644 --- a/packages/workflow/workflow-vm/tests/integration.spec.ts +++ b/packages/workflow/workflow-vm/tests/integration.spec.ts @@ -11,15 +11,17 @@ import SubagentService from '@deepseek-ai/dsh-subagent' import * as spawn from '@deepseek-ai/dsh-subagent-spawn' import { STRUCTURED_OUTPUT_TOOL } from '@deepseek-ai/dsh-subagent-inprocess' import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' -import VmWorkflowEngine from '../src/index.ts' +import WorkerWorkflowEngine from '../src/index.ts' type Script = ConstructorParameters[0] /** - * The whole in-process stack, keyless: the vm engine drives the REAL spawn - * backend (with its structured runtime) on a real agent loop; the scripted - * mock MODEL is the only mocked boundary. This is the integration guard the - * per-hook unit tests (which stub the subagent seam) structurally cannot give. + * The whole in-process stack, keyless, with the script in a REAL worker + * thread: the engine drives the REAL spawn backend (with its + * structured runtime) on a real agent loop; the scripted mock MODEL is the + * only mocked boundary. This is the guard the unit suites structurally + * cannot give — the MessageChannel suite fakes the host, and the host suite + * stubs the subagent seam. */ async function setup(script: Script) { const ctx = new Context() @@ -33,7 +35,7 @@ async function setup(script: Script) { await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SubagentService) await ctx.plugin(spawn, { providerName: 'spawn' }) - await ctx.plugin(VmWorkflowEngine, {}) + await ctx.plugin(WorkerWorkflowEngine, {}) ctx.llm.registerAdapter(['mock'], adapter) const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) return { ctx, parent, adapter } diff --git a/packages/workflow/workflow-vm/tests/session.spec.ts b/packages/workflow/workflow-vm/tests/session.spec.ts new file mode 100644 index 0000000000..00051ad56a --- /dev/null +++ b/packages/workflow/workflow-vm/tests/session.spec.ts @@ -0,0 +1,504 @@ +import { describe, expect, it, vi } from 'vitest' +import { MessageChannel } from 'node:worker_threads' +import type { MessagePort } from 'node:worker_threads' +import { HostToWorkerType, WorkerToHostType } from '../src/protocol.ts' +import type { HostToWorkerMessage, WorkerToHostMessage } from '../src/protocol.ts' +import { requireParentPort, runWorkerSession } from '../src/session.ts' +import type { ChildResult, WorkerInit } from '../src/types.ts' + +/** Default limits for in-process sessions (concurrency pinned; auto is machine-derived). */ +function limits(overrides?: Partial): WorkerInit['limits'] { + return { maxConcurrentAgents: 8, maxTotalAgents: 1000, maxItemsPerCall: 4096, syncTimeoutMs: 5000, ...overrides } +} + +/** Wrap a body in the minimal valid meta header (the session receives it pre-extracted). */ +function init(body: string, args?: unknown, limitOverrides?: Partial): WorkerInit { + return { + meta: { name: 'test-flow', description: 'a test workflow' }, + body, + ...args !== undefined ? { args } : {}, + limits: limits(limitOverrides), + } +} + +/** One scripted host over the other end of a MessageChannel. */ +interface FakeHost { + port: MessagePort + messages: WorkerToHostMessage[] + /** Messages of one type, as they arrive. */ + ofType(type: T): Extract[] + send(message: HostToWorkerMessage): void + /** Resolves with the terminal result message. */ + result(): Promise['result']> + close(): void +} + +interface FakeHostOptions { + /** Auto-respond to child-start: reply started + settled per child index. Omit a reply to leave the child pending. */ + reply?: (request: { prompt: string; schema?: unknown; model?: string }, index: number) => ChildResult | undefined + /** Reject the start instead (child-start-error) when returning a string. */ + refuse?: (index: number) => string | undefined + /** Auto-send `go` on `ready` (default true). */ + go?: boolean + /** Manual mode: do NOT auto-answer child-start at all (the test scripts the replies). */ + manual?: boolean +} + +/** + * Drive runWorkerSession IN-PROCESS over a MessageChannel: this is where the + * worker-side files earn their coverage — code inside a real Worker is + * invisible to main-process coverage. The fake host mirrors the real host's + * protocol discipline (one started/start-error per start; settled/disposed + * follow). + */ +function fakeHost(options?: FakeHostOptions): FakeHost { + const channel = new MessageChannel() + const messages: WorkerToHostMessage[] = [] + const resultGate = Promise.withResolvers['result']>() + let childIndex = 0 + channel.port1.on('message', (message: WorkerToHostMessage) => { + messages.push(message) + switch (message.type) { + case WorkerToHostType.Ready: + if (options?.go !== false) channel.port1.postMessage({ type: HostToWorkerType.Go } satisfies HostToWorkerMessage) + break + case WorkerToHostType.ChildStart: { + if (options?.manual) break + const index = childIndex + childIndex += 1 + const refusal = options?.refuse?.(index) + if (refusal !== undefined) { + channel.port1.postMessage( + { type: HostToWorkerType.ChildStartError, callId: message.callId, rendered: refusal } satisfies HostToWorkerMessage, + ) + break + } + channel.port1.postMessage({ type: HostToWorkerType.ChildStarted, callId: message.callId, childId: `child-${index}` } satisfies HostToWorkerMessage) + const reply = options?.reply?.(message.request, index) + if (reply !== undefined) { + channel.port1.postMessage( + { type: HostToWorkerType.ChildSettled, callId: message.callId, result: reply } satisfies HostToWorkerMessage, + ) + } + break + } + case WorkerToHostType.ChildDispose: + channel.port1.postMessage({ type: HostToWorkerType.ChildDisposed, callId: message.callId } satisfies HostToWorkerMessage) + break + case WorkerToHostType.Result: + resultGate.resolve(message.result) + break + default: + break + } + }) + return { + port: channel.port2, + messages, + ofType: type => messages.filter((message): message is never => message.type === type), + send: (message) => { channel.port1.postMessage(message) }, + result: () => resultGate.promise, + close: () => { channel.port1.close() }, + } +} + +/** A completed text child result. */ +function text(reply: string): ChildResult { + return { output: [{ type: 'text', text: reply }], stopReason: 'completed' } +} + +describe('runWorkerSession over an in-process MessageChannel', () => { + it('runs a script end to end: ready/go handshake, phases, log, agents, result', async () => { + const host = fakeHost({ reply: (_request, index) => text(`answer-${index}`) }) + const session = runWorkerSession(host.port, init(` + phase('Scan') + log('starting with ' + args.files.length + ' files') + const answers = await pipeline(args.files, (prev, item) => agent('read ' + item)) + return { answers } + `, { files: ['a.ts', 'b.ts'] })) + const result = await host.result() + await session + expect(result.stopReason).toBe('completed') + expect(result.agentsStarted).toBe(2) + expect(result.value).toEqual({ answers: ['answer-0', 'answer-1'] }) + expect(host.messages[0]!.type).toBe('ready') + expect(host.ofType(WorkerToHostType.Phase).map(m => m.title)).toEqual(['Scan']) + expect(host.ofType(WorkerToHostType.Log).map(m => m.message)).toEqual(['starting with 2 files']) + expect(host.ofType(WorkerToHostType.AgentStart).map(m => m.info.childId)).toEqual(['child-0', 'child-1']) + expect(host.ofType(WorkerToHostType.AgentEnd).every(m => m.info.outcome === 'completed')).toBe(true) + host.close() + }) + + it('agent({schema}) forwards the schema on the start request and returns the structured value', async () => { + const host = fakeHost({ reply: () => ({ output: [], structured: { files: ['x.ts'] }, stopReason: 'completed' }) }) + void runWorkerSession(host.port, init(` + const found = await agent('list files', { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } } }, model: 'deepseek-v4-pro' }) + return { first: found.files[0] } + `)) + const result = await host.result() + expect(result.value).toEqual({ first: 'x.ts' }) + const start = host.ofType(WorkerToHostType.ChildStart)[0]! + expect(start.request.schema).toEqual({ type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } } }) + expect(start.request.model).toBe('deepseek-v4-pro') + host.close() + }) + + it('a schema child completing WITHOUT a structured value resolves null with a failed outcome', async () => { + const host = fakeHost({ reply: () => text('prose, no structure') }) + void runWorkerSession(host.port, init("return await agent('p', { schema: { type: 'object' } })")) + const result = await host.result() + expect(result.value).toBeNull() + expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('failed') + host.close() + }) + + it('a child settling non-completed resolves null (scripts filter), never throwing into the script', async () => { + const host = fakeHost({ reply: (_request, index) => index === 0 ? { output: [], stopReason: 'error' } : text('ok') }) + void runWorkerSession(host.port, init("return await parallel([() => agent('one'), () => agent('two')])")) + const result = await host.result() + expect(result.value).toEqual([null, 'ok']) + expect(host.ofType(WorkerToHostType.AgentEnd).map(m => m.info.outcome)).toEqual(expect.arrayContaining(['failed', 'completed'])) + host.close() + }) + + it('a start refusal (child-start-error) is a fatal AGENT_START that kills the script through a combinator', async () => { + const host = fakeHost({ refuse: () => 'no provider here' }) + void runWorkerSession(host.port, init("return await pipeline([1], () => agent('p'))")) + const result = await host.result() + expect(result.stopReason).toBe('error') + expect(result.error).toContain('agent() could not start a child') + expect(result.error).toContain('no provider here') + host.close() + }) + + it('a child-failed message (infrastructure rejection) is fatal AGENT_RESULT with the paired failed outcome', async () => { + const host = fakeHost() + void runWorkerSession(host.port, init(` + try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, code: e.code, fatal: e.fatal } } + `)) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId + host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' }) + host.send({ type: HostToWorkerType.ChildFailed, callId, rendered: 'backend exploded' }) + const result = await host.result() + expect(result.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true }) + expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('failed') + host.close() + }) + + it('cancel before go: the body never runs at all and the result is cancelled (a second cancel is a no-op)', async () => { + const host = fakeHost({ go: false }) + const session = runWorkerSession(host.port, init("log('ran')\nreturn 123")) + await vi.waitFor(() => { expect(host.messages.some(m => m.type === WorkerToHostType.Ready)).toBe(true) }) + host.send({ type: HostToWorkerType.Cancel, reason: 'aborted before start' }) + // Idempotence: the first reason wins; a duplicate cancel changes nothing. + host.send({ type: HostToWorkerType.Cancel, reason: 'a later reason that must lose' }) + const result = await host.result() + await session + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('aborted before start') + expect(result.error).not.toContain('must lose') + expect(result.value).toBeNull() + expect(host.ofType(WorkerToHostType.Log)).toEqual([]) + host.close() + }) + + it('a script with no return value resolves value: null', async () => { + const host = fakeHost({ reply: () => text('ok') }) + void runWorkerSession(host.port, init("await agent('p')")) + const result = await host.result() + expect(result.stopReason).toBe('completed') + expect(result.value).toBeNull() + host.close() + }) + + it('cancel mid-run: in-flight children get cancel RPCs, hooks throw at entry, the run reports cancelled', async () => { + const host = fakeHost() + void runWorkerSession(host.port, init(` + phase('before') + try { await agent('x') } catch (e) {} + try { phase('after') } catch (e) {} + try { log('after') } catch (e) {} + try { await parallel([() => 'ran']) } catch (e) {} + try { await pipeline(['item'], p => p) } catch (e) {} + return 'survived by catching' + `)) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId + host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' }) + host.send({ type: HostToWorkerType.Cancel, reason: 'stop everything' }) + // The real host settles the aborted child; mirror it. + host.send({ type: HostToWorkerType.ChildSettled, callId, result: { output: [], stopReason: 'aborted' } }) + const result = await host.result() + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('stop everything') + expect(host.ofType(WorkerToHostType.ChildCancel).map(m => m.callId)).toContain(callId) + expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('cancelled') + // No post-cancel narration left the runtime (the hooks threw at entry). + expect(host.ofType(WorkerToHostType.Phase).map(m => m.title)).toEqual(['before']) + expect(host.ofType(WorkerToHostType.Log)).toEqual([]) + host.close() + }) + + it('cancellation between a queued waiter and its slot: the waiter rejects without a child-start', async () => { + const host = fakeHost({ go: true }) + void runWorkerSession(host.port, init( + "return await parallel([() => agent('a'), () => agent('b')])", + undefined, + { maxConcurrentAgents: 1 }, + )) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + host.send({ type: HostToWorkerType.Cancel, reason: 'raced' }) + const result = await host.result() + expect(result.stopReason).toBe('cancelled') + // Only the first agent ever reached the host. + expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) + host.close() + }) + + it('a stray (never-awaited) agent is reaped after settlement: cancel + dispose RPCs flow, no unhandled rejection', async () => { + const unhandled: unknown[] = [] + const onUnhandled = (reason: unknown): void => { unhandled.push(reason) } + process.on('unhandledRejection', onUnhandled) + try { + const host = fakeHost() + void runWorkerSession(host.port, init(` + agent('stray, never awaited') + return 'done without awaiting' + `)) + const result = await host.result() + expect(result.stopReason).toBe('completed') + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId + host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' }) + host.send({ type: HostToWorkerType.ChildSettled, callId, result: { output: [], stopReason: 'aborted' } }) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildDispose).map(m => m.callId)).toContain(callId) }) + await new Promise(resolve => setTimeout(resolve, 20)) + expect(unhandled).toEqual([]) + host.close() + } finally { + process.off('unhandledRejection', onUnhandled) + } + }) + + it('an unparseable body settles an error result instead of dying without one (host pre-parse skew guard)', async () => { + const host = fakeHost() + await runWorkerSession(host.port, init('return (((')) + const result = await host.result() + expect(result.stopReason).toBe('error') + expect(result.error).toContain('does not parse') + expect(result.agentsStarted).toBe(0) + host.close() + }) + + it('a synchronous spin in the initial slice dies by the in-worker vm timeout', async () => { + const host = fakeHost() + void runWorkerSession(host.port, init('while (true) {}', undefined, { syncTimeoutMs: 50 })) + const result = await host.result() + expect(result.stopReason).toBe('error') + expect(result.error?.toLowerCase()).toContain('timed out') + host.close() + }) + + it('a non-JSON return value fails loud as RESULT_UNSERIALIZABLE', async () => { + const host = fakeHost() + void runWorkerSession(host.port, init('return { when: new Date(0) }')) + const result = await host.result() + expect(result.stopReason).toBe('error') + expect(result.error).toContain('not plain JSON data') + host.close() + }) + + it('tolerates replies for unknown callIds (a teardown race): nothing crashes, the run completes', async () => { + const host = fakeHost({ reply: () => text('fine') }) + void runWorkerSession(host.port, init("return await agent('p')")) + host.send({ type: HostToWorkerType.ChildStarted, callId: 999, childId: 'ghost' }) + host.send({ type: HostToWorkerType.ChildStartError, callId: 999, rendered: 'ghost' }) + host.send({ type: HostToWorkerType.ChildSettled, callId: 999, result: text('ghost') }) + host.send({ type: HostToWorkerType.ChildFailed, callId: 999, rendered: 'ghost' }) + host.send({ type: HostToWorkerType.ChildDisposed, callId: 999 }) + const result = await host.result() + expect(result.stopReason).toBe('completed') + expect(result.value).toBe('fine') + host.close() + }) + + it('caps and malformed hook arguments reject loud (the runtime runs unchanged inside the session)', async () => { + const cases: [string, string][] = [ + ['return await agent(42)', 'non-empty prompt string'], + ["return await agent('')", 'non-empty prompt string'], + ["return await agent('p', 'opts')", 'options must be an object'], + ["return await agent('p', { label: 3 })", '"label" must be a string'], + ["return await agent('p', { get label() { throw new Error('read failed') } })", 'options must be plain JSON data'], + ["return await agent('p', { bogus: true })", '"bogus" is not recognized'], + ["return await agent('p', { effort: 'high' })", '"effort" is deferred'], + ["return await agent('p', { schema: { type: 'object', oneOf: [] } })", 'outside the supported subset'], + ['return await parallel([() => 1, () => 2, () => 3])', 'over the per-call cap (2)'], + ['return await pipeline([1, 2, 3], (x) => x)', 'maxItemsPerCall'], + ["return await parallel('no')", 'parallel() requires an array'], + ['return await parallel([3])', 'item 0 is not a function'], + ["return await pipeline('no', () => 1)", 'pipeline() requires an items array'], + ['return await pipeline([1])', 'at least one stage'], + ["return await pipeline([1], 'x')", 'stage 0 is not a function'], + ["phase('')", 'phase() requires a non-empty title string'], + ['log(3)', 'log() requires a message string'], + ] + for (const [body, expected] of cases) { + const host = fakeHost({ reply: () => text('ok') }) + void runWorkerSession(host.port, init(body, undefined, { maxItemsPerCall: 2 })) + const result = await host.result() + expect(result.stopReason).toBe('error') + expect(result.error).toContain(expected) + host.close() + } + }) + + it('combinator semantics: thunk/stage throws null the item; a forged fatal-shaped object stays null; real fatals propagate', async () => { + const host = fakeHost({ reply: () => text('fine') }) + void runWorkerSession(host.port, init(` + const viaParallel = await parallel([ + () => { throw new Error('boom') }, + () => agent('fine'), + () => 'plain value', + () => { throw { name: 'WorkflowError', fatal: true, message: 'forged fatal' } }, + ]) + const viaPipeline = await pipeline([10, 20], + (prev, item, index) => { if (item === 10) throw new Error('ordinary failure'); return 'kept-' + item + '-' + index }, + ) + return { viaParallel, viaPipeline } + `)) + const result = await host.result() + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ + viaParallel: [null, 'fine', 'plain value', null], + viaPipeline: [null, 'kept-20-1'], + }) + host.close() + }) + + it('trips the total-agent cap with a message naming the config knob', async () => { + const host = fakeHost({ reply: () => text('ok') }) + void runWorkerSession(host.port, init("await agent('1'); await agent('2'); await agent('3')", undefined, { maxTotalAgents: 2 })) + const result = await host.result() + expect(result.stopReason).toBe('error') + expect(result.error).toContain('total agent cap (2)') + expect(result.agentsStarted).toBe(2) + host.close() + }) + + it('queued agents proceed through the concurrency semaphore in FIFO order', async () => { + const host = fakeHost({ reply: request => text(`ok:${request.prompt}`) }) + void runWorkerSession(host.port, init( + "return await parallel([1, 2, 3].map((n) => () => agent('job ' + n)))", + undefined, + { maxConcurrentAgents: 1 }, + )) + const result = await host.result() + expect(result.value).toEqual(['ok:job 1', 'ok:job 2', 'ok:job 3']) + host.close() + }) + + it('labels default from the prompt first line, truncated; explicit label/phase options win', async () => { + const host = fakeHost({ reply: () => text('ok') }) + void runWorkerSession(host.port, init(` + phase('Find') + await agent('a prompt that is quite long and will surely get truncated down to a display label\\n' + + 'with a second line the label must not include') + await agent('short', { label: 'named', phase: 'Custom' }) + return null + `)) + await host.result() + const starts = host.ofType(WorkerToHostType.AgentStart).map(m => m.info) + expect(starts[0]).toMatchObject({ seq: 1, phase: 'Find' }) + expect(starts[0]!.label.length).toBeLessThanOrEqual(48) + expect(starts[0]!.label).not.toContain('second line') + expect(starts[1]).toMatchObject({ seq: 2, label: 'named', phase: 'Custom' }) + host.close() + }) + + it('non-text output blocks are filtered out of the text result', async () => { + const host = fakeHost({ + reply: () => ({ + output: [ + { type: 'text', text: 'first ' }, + { type: 'tool_call', id: 'c1', name: 'x', arguments: {} } as never, + { type: 'text', text: 'second' }, + ], + stopReason: 'completed', + }), + }) + void runWorkerSession(host.port, init("return await agent('p')")) + const result = await host.result() + expect(result.value).toBe('first second') + host.close() + }) + + it('a cancel landing DURING the start round-trip winds the fresh child down (cancel + dispose) and dies cancelled', async () => { + const host = fakeHost({ manual: true }) + void runWorkerSession(host.port, init("return await agent('p')")) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId + // Cancel FIRST, then the (stale) started reply: the worker processes them + // in order, so the agent() continuation resumes already-cancelled — the + // window the real host cannot produce (it refuses starts once cancelled) + // but a teardown race can. + host.send({ type: HostToWorkerType.Cancel, reason: 'raced the start' }) + host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' }) + const result = await host.result() + expect(result.stopReason).toBe('cancelled') + await vi.waitFor(() => { + expect(host.ofType(WorkerToHostType.ChildCancel).map(m => m.callId)).toContain(callId) + expect(host.ofType(WorkerToHostType.ChildDispose).map(m => m.callId)).toContain(callId) + }) + // The child never became an agent-start: it was wound down pre-lifecycle. + expect(host.ofType(WorkerToHostType.AgentStart)).toEqual([]) + host.close() + }) + + it('a start refusal arriving after a cancel reads as the cancellation, not a broken seam', async () => { + const host = fakeHost({ manual: true }) + void runWorkerSession(host.port, init(` + try { await agent('p'); return 'unreachable' } catch (e) { return { code: e.code } } + `)) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId + host.send({ type: HostToWorkerType.Cancel, reason: 'stopping' }) + host.send({ type: HostToWorkerType.ChildStartError, callId, rendered: 'workflow run cancelled: stopping' }) + const result = await host.result() + // The run reports cancelled (the script died of CANCELLED, not AGENT_START). + expect(result.stopReason).toBe('cancelled') + host.close() + }) + + it('a child result rejection while cancelled pairs a cancelled agent-end, and the run reports cancelled', async () => { + const host = fakeHost({ manual: true }) + void runWorkerSession(host.port, init("return await agent('doomed')")) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) }) + const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId + host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' }) + await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.AgentStart).length).toBe(1) }) + host.send({ type: HostToWorkerType.Cancel, reason: 'user aborted' }) + host.send({ type: HostToWorkerType.ChildFailed, callId, rendered: 'backend crashed on abort' }) + const result = await host.result() + expect(result.stopReason).toBe('cancelled') + expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('cancelled') + host.close() + }) + +}) + +describe('the worker bootstrap', () => { + it('requireParentPort narrows a real port and throws on the main thread', () => { + const channel = new MessageChannel() + expect(requireParentPort(channel.port1)).toBe(channel.port1) + channel.port1.close() + expect(() => requireParentPort(null)).toThrow(/inside a worker thread/) + }) + + it('the entry module itself throws when loaded on the main thread (no parentPort)', async () => { + // This import EXECUTES ../src/worker.ts on the main thread, which is what + // covers the bootstrap file: requireParentPort throws before + // runWorkerSession is reached. + await expect(import('../src/worker.ts')).rejects.toThrow(/inside a worker thread/) + }) +}) diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts index bb685f536f..7264877f48 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts @@ -6,14 +6,17 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import SubagentService from '@deepseek-ai/dsh-subagent' import type { SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent' import type { WorkflowResult, WorkflowResultInfo, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' -import * as vmEngineModule from '../src/index.ts' -import VmWorkflowEngine, { type Config } from '../src/index.ts' +import * as workerEngineModule from '../src/index.ts' +import WorkerWorkflowEngine, { type Config } from '../src/index.ts' /** A minimal parent stand-in: the engine only threads it through to the provider. */ function fakeParent(): Agent { return { id: AgentId('workflow-parent'), options: {} } as unknown as Agent } +/** The vm-context escape hatch, spelled once: real Worker tests use it to make the WORKER misbehave. */ +const ESCAPE = "globalThis.constructor.constructor('return process')()" + /** One controllable child run: the test (or auto mode) settles it. */ interface ControlledRun { request: SubagentStartRequest @@ -25,13 +28,11 @@ interface ControlledRun { /** * A scripted in-test provider over the REAL SubagentService registry: `auto` * settles each run via the reply function on a microtask; `manual` piles runs - * up in `runs` for the test to settle (concurrency/cancellation tests). A run - * aborts (settles `aborted`) when the request signal fires, like the real - * in-process backends. + * up in `runs` for the test to settle. A run aborts (settles `aborted`) when + * the request signal fires, like the real in-process backends. */ class StubProvider implements SubagentProvider { readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true } - // Context contract: stub children start fresh, mirroring the spawn backend. readonly inheritsParentContext = false readonly runs: ControlledRun[] = [] @@ -64,7 +65,6 @@ class StubProvider implements SubagentProvider { controlled.disposed = true return Promise.resolve() } - // A slow-winding child (quiescence tests): disposal completes late. return new Promise((resolve) => { setTimeout(() => { controlled.disposed = true @@ -99,8 +99,8 @@ async function setup(options?: SetupOptions) { ctx.subagents.registerProvider(provider) // A fixed concurrency ceiling: the auto-resolved default is machine-derived // (cores - 2, floored at 1), so tests that expect N children in flight - // would wedge on small CI runners. Tests about the ceiling override it. - await ctx.plugin(VmWorkflowEngine, { provider: 'stub', maxConcurrentAgents: 8, ...options?.config }) + // would wedge on small CI runners. + await ctx.plugin(WorkerWorkflowEngine, { provider: 'stub', maxConcurrentAgents: 8, ...options?.config }) return { ctx, provider, parent: fakeParent() } } @@ -120,8 +120,8 @@ async function run(ctx: Context, parent: Agent, source: string, args?: unknown): } describe('dsh-workflow-vm', () => { - describe('script execution', () => { - it('runs a script end-to-end: agent() text results, phases, log, args, return value', async () => { + describe('script execution over a real worker thread', () => { + it('runs a script end-to-end: agent() text results, phases, log, args, return value, events', async () => { const { ctx, parent, provider } = await setup({ reply: (_request, index) => text(`answer-${index}`) }) const events: [string, unknown[]][] = [] for (const name of ['workflow/start', 'workflow/phase', 'workflow/log', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) { @@ -152,32 +152,12 @@ describe('dsh-workflow-vm', () => { expect('value' in end).toBe(false) }) - it('agent-start/end events carry seq, label (defaulted from the prompt), phase, and outcome', async () => { - const { ctx, parent } = await setup() - const starts: unknown[] = [] - const ends: unknown[] = [] - ctx.on('workflow/agent-start', (_info, agent) => starts.push(agent)) - ctx.on('workflow/agent-end', (_info, agent) => ends.push(agent)) - await run(ctx, parent, script(` - phase('Find') - await agent('a prompt that is quite long and will surely get truncated down to a display label\\n' - + 'with a second line the label must not include') - await agent('short', { label: 'named', phase: 'Custom' }) - return null - `)) - expect(starts[0]).toMatchObject({ seq: 1, phase: 'Find', childId: 'stub-child-0' }) - expect((starts[0] as { label: string }).label.length).toBeLessThanOrEqual(48) - expect((starts[0] as { label: string }).label).not.toContain('second line') - expect(starts[1]).toMatchObject({ seq: 2, label: 'named', phase: 'Custom' }) - expect(ends[0]).toMatchObject({ seq: 1, outcome: 'completed' }) - }) - - it('agent({schema}) forwards outputSchema to the provider and returns the structured value into the realm', async () => { + it('agent({schema, model}) forwards outputSchema and agentOptions to the provider across the thread', async () => { const { ctx, parent, provider } = await setup({ reply: () => ({ output: [], structured: { files: ['x.ts', 'y.ts'] }, stopReason: 'completed' }), }) const result = await run(ctx, parent, script(` - const found = await agent('list files', { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'] } }) + const found = await agent('list files', { model: 'deepseek-v4-pro', schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'] } }) return { first: found.files[0], count: found.files.length } `)) expect(result.value).toEqual({ first: 'x.ts', count: 2 }) @@ -186,271 +166,25 @@ describe('dsh-workflow-vm', () => { properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'], }) - }) - - it('model option maps to agentOptions.model on the start request', async () => { - const { ctx, parent, provider } = await setup() - await run(ctx, parent, script("return await agent('p', { model: 'deepseek-v4-pro' })")) expect(provider.runs[0]!.request.agentOptions).toEqual({ model: 'deepseek-v4-pro' }) + expect(provider.runs[0]!.request.parent).toBeDefined() }) - it('a failed child resolves null (scripts filter), never throwing into the script', async () => { - const { ctx, parent } = await setup({ - reply: (_request, index) => index === 0 ? { output: [], stopReason: 'error' } : text('ok'), - }) - const result = await run(ctx, parent, script(` - const results = await parallel([() => agent('one'), () => agent('two')]) - return results - `)) - expect(result.value).toEqual([null, 'ok']) - }) - - it('a schema run that completes WITHOUT a structured value is a child failure (null + failed outcome)', async () => { - const { ctx, parent } = await setup({ reply: () => text('prose, no structure') }) - const ends: unknown[] = [] - ctx.on('workflow/agent-end', (_info, agent) => ends.push(agent)) - const result = await run(ctx, parent, script(` - return await agent('p', { schema: { type: 'object' } }) - `)) - expect(result.value).toBeNull() - expect(ends[0]).toMatchObject({ outcome: 'failed' }) - }) - - it('a script with no return value resolves value: null', async () => { + it('a fatal hook error inside the worker kills the script and reports the error', async () => { const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("await agent('p')")) - expect(result.stopReason).toBe('completed') - expect(result.value).toBeNull() - }) - - it('a returned promise/thenable resolves per async-JS semantics before materialization', async () => { - const { ctx, parent } = await setup() - // Load-bearing ergonomics: forgetting await on the final hook call works. - expect((await run(ctx, parent, script("return agent('x')"))).value).toBe('stub reply') - // A hand-built thenable is assimilated by the async return — the - // RESOLUTION is the script's return value (standard JavaScript), and the - // realm-boundary guard applies to that resolution, not the thenable. - expect((await run(ctx, parent, script('return { value: 1, then(resolve) { resolve({ ok: true }) } }'))).value).toEqual({ ok: true }) - const nonJson = await run(ctx, parent, script('return { then(resolve) { resolve({ bad: new Date(0) }) } }')) - expect(nonJson.stopReason).toBe('error') - expect(nonJson.error).toContain('not plain JSON data') - }) - }) - - describe('combinator semantics', () => { - it('pipeline has NO cross-stage barrier: a fast item finishes stage 2 while a slow item holds stage 1', async () => { - const { ctx, parent, provider } = await setup({ manual: true }) - const handle = ctx.workflows.start({ - script: script(` - const out = await pipeline(['slow', 'fast'], - (prev, item) => agent('s1 ' + item), - (prev, item) => agent('s2 ' + item + ' after ' + prev), - ) - return out - `), - parent: fakeParent(), - }) - // Both items enter stage 1 concurrently. - await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) - // Settle only the FAST item's stage 1 → its stage 2 starts with no barrier. - provider.runs[1]!.settle(text('fast-1')) - await vi.waitFor(() => { expect(provider.runs.length).toBe(3) }) - expect((provider.runs[2]!.request.prompt[0] as { text: string }).text).toBe('s2 fast after fast-1') - // The slow item is still sitting in stage 1. - provider.runs[2]!.settle(text('fast-2')) - provider.runs[0]!.settle(text('slow-1')) - await vi.waitFor(() => { expect(provider.runs.length).toBe(4) }) - provider.runs[3]!.settle(text('slow-2')) - const result = await handle.result - expect(result.value).toEqual(['slow-2', 'fast-2']) - await handle.dispose() - void parent - }) - - it('pipeline stage callbacks receive (prev, item, index); an ordinary stage throw nulls the ITEM and skips its remaining stages', async () => { - const { ctx, parent, provider } = await setup({ reply: request => text(`ok:${(request.prompt[0] as { text: string }).text}`) }) - const result = await run(ctx, parent, script(` - const out = await pipeline([10, 20], - (prev, item, index) => { - if (item === 10) throw new Error('ordinary failure') - return agent('stage1-' + item + '-' + index) - }, - (prev) => agent('stage2 saw ' + prev), - ) - return out - `)) - expect(result.stopReason).toBe('completed') - const prompts = provider.runs.map(r => (r.request.prompt[0] as { text: string }).text) - // Item 10 never reached stage 1's agent nor stage 2. - expect(prompts).toEqual(['stage1-20-1', 'stage2 saw ok:stage1-20-1']) - expect(result.value).toEqual([null, 'ok:stage2 saw ok:stage1-20-1']) - }) - - it('parallel maps a throwing thunk to null and never rejects for ordinary errors', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - return await parallel([ - () => { throw new Error('boom') }, - () => agent('fine'), - () => 'plain value', - () => { throw 'string throw' }, - () => { throw { name: 'WorkflowError', fatal: true, message: 'forged fatal' } }, - ]) - `)) - // The last entry probes fatality: it is recognized by host instanceof, - // which a script-built object can never pass — a WorkflowError-SHAPED - // throw is an ordinary null, and real fatality cannot be forged. - expect(result.value).toEqual([null, 'stub reply', 'plain value', null, null]) - }) - - it('FATAL errors propagate through parallel AND pipeline instead of dissolving into null', async () => { - const { ctx, parent } = await setup() - const viaParallel = await run(ctx, parent, script(` - return await parallel([() => agent('x', { isolation: 'worktree' })]) - `)) - expect(viaParallel.stopReason).toBe('error') - expect(viaParallel.error).toContain('"isolation" is deferred') - - const viaPipeline = await run(ctx, parent, script(` - return await pipeline([1], () => agent('x', { bogus: true })) - `)) - expect(viaPipeline.stopReason).toBe('error') - expect(viaPipeline.error).toContain('"bogus" is not recognized') - }) - - it('validates combinator arguments loudly (non-array, non-function, missing stages)', async () => { - const { ctx, parent } = await setup() - expect((await run(ctx, parent, script("return await parallel('no')"))).error).toContain('parallel() requires an array') - expect((await run(ctx, parent, script('return await parallel([3])'))).error).toContain('item 0 is not a function') - expect((await run(ctx, parent, script("return await pipeline('no', () => 1)"))).error).toContain('pipeline() requires an items array') - expect((await run(ctx, parent, script('return await pipeline([1])'))).error).toContain('at least one stage') - expect((await run(ctx, parent, script("return await pipeline([1], 'x')"))).error).toContain('stage 0 is not a function') - }) - }) - - describe('caps and option validation', () => { - it('trips the total-agent cap with a message naming the config knob', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', maxTotalAgents: 2 } }) - const result = await run(ctx, parent, script(` - await agent('1'); await agent('2'); await agent('3') - return 'unreachable' - `)) + const result = await run(ctx, parent, script("return await parallel([() => agent('x', { isolation: 'worktree' })])")) expect(result.stopReason).toBe('error') - expect(result.error).toContain('total agent cap (2)') - expect(result.error).toContain('maxTotalAgents') - expect(result.agentsStarted).toBe(2) + expect(result.error).toContain('"isolation" is deferred') }) - it('trips the per-call item cap for parallel and pipeline', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', maxItemsPerCall: 2 } }) - expect((await run(ctx, parent, script('return await parallel([() => 1, () => 2, () => 3])'))).error) - .toContain('over the per-call cap (2)') - expect((await run(ctx, parent, script('return await pipeline([1, 2, 3], (x) => x)'))).error) - .toContain('maxItemsPerCall') - }) - - it('enforces the concurrency ceiling: never more than maxConcurrentAgents children in flight', async () => { - const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 2 } }) - const handle = ctx.workflows.start({ - script: script("return await parallel([1, 2, 3, 4, 5].map((n) => () => agent('job ' + n)))"), - parent, - }) - // Only 2 children may exist until one settles. - await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) - await new Promise(resolve => setTimeout(resolve, 20)) - expect(provider.runs.length).toBe(2) - // Settle children in arrival order; after each settle at most ONE more - // child may enter — the window never exceeds the ceiling. - for (let index = 0; index < 5; index++) { - await vi.waitFor(() => { expect(provider.runs.length).toBeGreaterThan(index) }) - expect(provider.runs.length).toBeLessThanOrEqual(Math.min(index + 2, 5)) - provider.runs[index]!.settle(text(`r${index}`)) - } - const result = await handle.result - expect(result.stopReason).toBe('completed') - expect(result.agentsStarted).toBe(5) - expect(result.value).toEqual(['r0', 'r1', 'r2', 'r3', 'r4']) - await handle.dispose() - }) - - it('rejects malformed agent() arguments and option types loudly', async () => { - const { ctx, parent } = await setup() - expect((await run(ctx, parent, script('return await agent(42)'))).error).toContain('non-empty prompt string') - expect((await run(ctx, parent, script("return await agent('')"))).error).toContain('non-empty prompt string') - expect((await run(ctx, parent, script("return await agent('p', 'opts')"))).error).toContain('options must be an object') - expect((await run(ctx, parent, script("return await agent('p', { label: 3 })"))).error).toContain('"label" must be a string') - expect((await run(ctx, parent, script("return await agent('p', { effort: 'high' })"))).error).toContain('"effort" is deferred') - }) - - it('rejects options whose property reads throw (materialization is loud, not silent)', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("return await agent('p', { get label() { throw new Error('read failed') } })")) - expect(result.stopReason).toBe('error') - expect(result.error).toContain('options must be plain JSON data') - expect(result.error).toContain('read failed') - }) - - it('validates phase() and log() arguments loudly', async () => { - const { ctx, parent } = await setup() - expect((await run(ctx, parent, script('phase(3)'))).error).toContain('phase() requires a non-empty title string') - expect((await run(ctx, parent, script("phase('')"))).error).toContain('phase() requires a non-empty title string') - expect((await run(ctx, parent, script('log(3)'))).error).toContain('log() requires a message string') - }) - - it('rejects an unsupported schema via the shared subset assertion (UNSUPPORTED_SCHEMA)', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("return await agent('p', { schema: { type: 'object', oneOf: [] } })")) - expect(result.stopReason).toBe('error') - expect(result.error).toContain('outside the supported subset') - expect(result.error).toContain('oneOf') - }) - - it('wraps a provider start failure as a fatal AGENT_START error (a missing provider cannot dissolve into null)', async () => { + it('a provider start failure crosses back as a fatal AGENT_START error', async () => { const { ctx, parent } = await setup({ config: { provider: 'nonexistent' } }) const result = await run(ctx, parent, script("return await pipeline([1], () => agent('p'))")) expect(result.stopReason).toBe('error') - expect(result.error).toContain('could not start a child on provider "nonexistent"') - }) - }) - - describe('the value boundary', () => { - it('args are cloned at start: a script scribbling on them cannot mutate the caller\'s object', async () => { - const { ctx, parent } = await setup() - const hostArgs = { files: ['a.ts'], nested: { deep: [1, 2] } } - const result = await run(ctx, parent, script(` - args.files.push('b.ts') - return { count: args.files.length, deep: args.nested.deep[1] } - `), hostArgs) - expect(result.value).toEqual({ count: 2, deep: 2 }) - // The caller's object is untouched (the engine cloned args host-side). - expect(hostArgs.files).toEqual(['a.ts']) + expect(result.error).toContain('agent() could not start a child') }) - it('scalar/null args pass through directly; absent args leave the global undefined', async () => { - const { ctx, parent } = await setup() - expect((await run(ctx, parent, script('return args * 2'), 21)).value).toBe(42) - expect((await run(ctx, parent, script('return args === null'), null)).value).toBe(true) - expect((await run(ctx, parent, script('return typeof args'))).value).toBe('undefined') - }) - - it('hook failures reach the script as HOST WorkflowErrors: fields readable, in-realm instanceof Error is false', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - try { - await agent('p', { bogus: true }) - return 'unreachable' - } catch (e) { - // The documented consequence of the trust premise: hook errors are - // host objects, so realm instanceof is false — read the fields. - return { isRealmError: e instanceof Error, name: e.name, code: e.code, fatal: e.fatal, message: e.message } - } - `)) - expect(result.stopReason).toBe('completed') - expect(result.value).toMatchObject({ isRealmError: false, name: 'WorkflowError', code: 'UNSUPPORTED_OPTION', fatal: true }) - expect((result.value as { message: string }).message).toContain('"bogus" is not recognized') - }) - - it('a rejecting provider result is an infrastructure fault: fatal AGENT_RESULT, agent-end paired, no combinator dissolve', async () => { + it('a child result REJECTION crosses back as a fatal AGENT_RESULT error (a broken provider is not a failed child)', async () => { const ctx = new Context() await ctx.plugin(SubagentService) const provider: SubagentProvider = { @@ -465,184 +199,90 @@ describe('dsh-workflow-vm', () => { }), } ctx.subagents.registerProvider(provider) - await ctx.plugin(VmWorkflowEngine, { provider: 'rejecting' }) - const ends: unknown[] = [] - ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) }) - // Direct await: the script reads the typed fields (a host object, so - // realm instanceof is false — same as every hook failure). - const direct = await run(ctx, fakeParent(), script(` + await ctx.plugin(WorkerWorkflowEngine, { provider: 'rejecting', maxConcurrentAgents: 2 }) + const result = await run(ctx, fakeParent(), script(` try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, code: e.code, fatal: e.fatal, message: e.message } } `)) - expect(direct.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true }) - expect((direct.value as { message: string }).message).toContain('backend exploded') - // The child's lifecycle stays paired even though result never resolved. - expect(ends).toEqual([expect.objectContaining({ seq: 1, outcome: 'failed' })]) - // Through a combinator the fault PROPAGATES (fatal) — a broken provider - // must not dissolve into the per-item null and read as a failed child. - const throughParallel = await run(ctx, fakeParent(), script("return await parallel([() => agent('p')])")) - expect(throughParallel.stopReason).toBe('error') - expect(throughParallel.error).toContain('backend exploded') + expect(result.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true }) + expect((result.value as { message: string }).message).toContain('backend exploded') }) - it('phase()/log() throw host WorkflowErrors synchronously on misuse', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - try { phase(3) } catch (e) { - if (e.name !== 'WorkflowError') throw e - } - try { log(3) } catch (e) { - return { name: e.name, message: e.message } - } - `)) - expect(result.value).toMatchObject({ name: 'WorkflowError' }) - expect((result.value as { message: string }).message).toContain('log() requires') + it('a child whose dispose() rejects cannot wedge the script (the host acks anyway)', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + const provider: SubagentProvider = { + name: 'bad-dispose', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + inheritsParentContext: false, + start: () => ({ + id: AgentId('bad-dispose-child'), + result: Promise.resolve({ output: [{ type: 'text', text: 'fine' }], stopReason: 'completed' }), + cancel: () => { /* settled already */ }, + dispose: () => Promise.reject(new Error('dispose exploded')), + }), + } + ctx.subagents.registerProvider(provider) + await ctx.plugin(WorkerWorkflowEngine, { provider: 'bad-dispose', maxConcurrentAgents: 2 }) + const result = await run(ctx, fakeParent(), script("return await agent('p')")) + expect(result.stopReason).toBe('completed') + expect(result.value).toBe('fine') }) - it('a returned value whose property reads throw fails loud as RESULT_UNSERIALIZABLE', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - return { get a() { throw new Error('read failed') } } - `)) - expect(result.stopReason).toBe('error') - expect(result.error).toContain('not plain JSON data') - expect(result.error).toContain('read failed') - }) - - it('a non-JSON return value fails loud as RESULT_UNSERIALIZABLE', async () => { - const { ctx, parent } = await setup() - const withDate = await run(ctx, parent, script('return { when: new Date(0) }')) - expect(withDate.stopReason).toBe('error') - expect(withDate.error).toContain('not plain JSON data') - const withFn = await run(ctx, parent, script('return { fn: () => 1 }')) - expect(withFn.error).toContain('not plain JSON data') - }) - - it('kills a synchronous spin in the initial slice via the vm timeout', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', syncTimeoutMs: 50 } }) - const result = await run(ctx, parent, script('while (true) {}')) - expect(result.stopReason).toBe('error') - expect(result.error?.toLowerCase()).toContain('timed out') + it('a child dispose() rejecting an UNRENDERABLE value still acks — the containment warn is total', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + const provider: SubagentProvider = { + name: 'coercion-trap-dispose', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + inheritsParentContext: false, + start: () => ({ + id: AgentId('trap-child'), + result: Promise.resolve({ output: [{ type: 'text', text: 'fine' }], stopReason: 'completed' }), + cancel: () => { /* settled already */ }, + // The rejection VALUE's own coercion throws: a warn built with bare + // String(error) would itself throw, skipping the ChildDisposed ack + // and wedging the script's finally until the grace/terminate path. + // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- the non-Error rejection IS the scenario under test + dispose: () => Promise.reject({ toString: () => { throw new Error('coercion trap') } }), + }), + } + ctx.subagents.registerProvider(provider) + await ctx.plugin(WorkerWorkflowEngine, { provider: 'coercion-trap-dispose', maxConcurrentAgents: 2 }) + const result = await run(ctx, fakeParent(), script("return await agent('p')")) + expect(result.stopReason).toBe('completed') + expect(result.value).toBe('fine') }) }) - describe('lifecycle: parse errors, cancellation, disposal', () => { - it('start() throws synchronously for an unparseable script or invalid meta', async () => { + describe('lifecycle: parse errors, cancellation, termination, disposal', () => { + it('start() throws synchronously for an unparseable script or invalid meta (host-side pre-parse)', async () => { const { ctx, parent } = await setup() expect(() => ctx.workflows.start({ script: 'const x = 1', parent })).toThrow(/must begin with/) expect(() => ctx.workflows.start({ script: script('return ((('), parent })).toThrow(/does not parse/) }) - it('cancel() aborts in-flight children and settles the run cancelled', async () => { + it('cancel() aborts in-flight children (signal AND cancel RPC) and settles the run cancelled', async () => { const { ctx, parent, provider } = await setup({ manual: true }) - const ends: WorkflowResultInfo[] = [] - ctx.on('workflow/end', (_info, result) => { ends.push(result) }) + const ends: unknown[] = [] + ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) }) + const runEnds: WorkflowResultInfo[] = [] + ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) const handle = ctx.workflows.start({ script: script("return await agent('long job')"), parent }) await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) handle.cancel('user stopped it') const result = await handle.result expect(result.stopReason).toBe('cancelled') expect(result.error).toContain('user stopped it') + await handle.dispose() expect(provider.runs[0]!.disposed).toBe(true) + expect(ends).toEqual([expect.objectContaining({ seq: 1, outcome: 'cancelled' })]) // workflow/end is an observer's only death signal: it fires for a // cancelled run too, mirroring the settled outcome data. - expect(ends).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: 1 }]) - await handle.dispose() + expect(runEnds).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: result.agentsStarted }]) }) - it('cancellation bridges to run.cancel() on every in-flight child, not just the request signal', async () => { - const { ctx, parent, provider } = await setup({ manual: true }) - const handle = ctx.workflows.start({ - script: script("return await parallel([() => agent('a'), () => agent('b')])"), - parent, - }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) - handle.cancel('bridged') - expect((await handle.result).stopReason).toBe('cancelled') - // The seam leaves a provider free to honor run.cancel() rather than the - // request signal, so the engine must drive BOTH channels per child. - expect(provider.runs.map(r => r.cancelled)).toEqual(['bridged', 'bridged']) - await handle.dispose() - }) - - it('a provider whose result REJECTS on abort still gets a paired cancelled agent-end, and the run reports cancelled', async () => { - const ctx = new Context() - await ctx.plugin(SubagentService) - // The seam allows result to reject for infrastructure faults; a backend - // that tears down uncleanly on abort exercises the rejection path WHILE - // the run is cancelled — which must stay a cancellation, not AGENT_RESULT. - const provider: SubagentProvider = { - name: 'reject-on-abort', - capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, - inheritsParentContext: false, - start: request => ({ - id: AgentId('crashing-child'), - result: new Promise((_, reject) => { - request.signal?.addEventListener('abort', () => { reject(new Error('backend crashed on abort')) }, { once: true }) - }), - cancel: () => { /* the signal listener above is the teardown */ }, - dispose: () => Promise.resolve(), - }), - } - ctx.subagents.registerProvider(provider) - await ctx.plugin(VmWorkflowEngine, { provider: 'reject-on-abort' }) - const starts: unknown[] = [] - const ends: unknown[] = [] - ctx.on('workflow/agent-start', (_info, agent) => { starts.push(agent) }) - ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) }) - const handle = ctx.workflows.start({ script: script("return await agent('doomed')"), parent: fakeParent() }) - await vi.waitFor(() => { expect(starts.length).toBe(1) }) - handle.cancel('user aborted') - const result = await handle.result - expect(result.stopReason).toBe('cancelled') - expect(result.error).toContain('user aborted') - expect(ends).toEqual([expect.objectContaining({ seq: 1, outcome: 'cancelled' })]) - await handle.dispose() - }) - - it('after cancellation EVERY hook throws at entry — phase/log/parallel/pipeline, not just agent()', async () => { - const { ctx, parent, provider } = await setup({ manual: true }) - let cancelled = false - const postCancel: string[] = [] - ctx.on('workflow/phase', (_info, title) => { if (cancelled) postCancel.push(`phase:${title}`) }) - ctx.on('workflow/log', (_info, message) => { if (cancelled) postCancel.push(`log:${message}`) }) - const handle = ctx.workflows.start({ - // The script survives each throw by catching, so every guarded hook is - // actually ATTEMPTED after the cancel; the run still reports cancelled. - script: script(` - phase('before') - try { await agent('x') } catch (e) {} - try { phase('after') } catch (e) {} - try { log('after') } catch (e) {} - try { await parallel([() => 'ran']) } catch (e) {} - try { await pipeline(['item'], p => p) } catch (e) {} - return 'survived by catching' - `), - parent, - }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) - cancelled = true - handle.cancel('stop everything') - const result = await handle.result - expect(result.stopReason).toBe('cancelled') - // No post-cancel progress ever reached observers, and no child started. - expect(postCancel).toEqual([]) - expect(provider.runs.length).toBe(1) - await handle.dispose() - }) - - it('an already-aborted request signal cancels before any child starts', async () => { - const { ctx, parent, provider } = await setup({ manual: true }) - const controller = new AbortController() - controller.abort() - const handle = ctx.workflows.start({ script: script("return await agent('never')"), parent, signal: controller.signal }) - const result = await handle.result - expect(result.stopReason).toBe('cancelled') - expect(provider.runs.length).toBe(0) - await handle.dispose() - }) - - it('an already-aborted signal cancels a HOOK-FREE script: the body never runs at all', async () => { - const { ctx, parent } = await setup() + it('an already-aborted request signal cancels before the body ever runs (the go handshake holds it)', async () => { + const { ctx, parent, provider } = await setup() const controller = new AbortController() controller.abort() const logs: string[] = [] @@ -652,151 +292,80 @@ describe('dsh-workflow-vm', () => { expect(result.stopReason).toBe('cancelled') expect(result.value).toBeNull() expect(logs).toEqual([]) + expect(provider.runs.length).toBe(0) await handle.dispose() }) - it('cancel() right after start() reports cancelled even when the script needed no hooks', async () => { - const { ctx, parent } = await setup() - const handle = ctx.workflows.start({ script: script('return 123'), parent }) - handle.cancel('changed my mind') - const result = await handle.result - expect(result.stopReason).toBe('cancelled') - expect(result.value).toBeNull() - expect(result.error).toContain('changed my mind') - await handle.dispose() - }) - - it('an agent() call AFTER a mid-run cancel rejects at entry — no child ever starts', async () => { + it('cancel() right after start() cancels before the body runs; the signal aborting mid-run cancels like cancel()', async () => { const { ctx, parent, provider } = await setup({ manual: true }) - const handle = ctx.workflows.start({ - script: script(` - await agent('first') - return await agent('second') - `), - parent, - }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) - // Same synchronous block: the first child settles completed, then the - // cancel lands BEFORE the script's continuation can call agent() again. - provider.runs[0]!.settle(text('first done')) - handle.cancel('mid-run') - const result = await handle.result - expect(result.stopReason).toBe('cancelled') - expect(provider.runs.length).toBe(1) - await handle.dispose() - }) + const first = ctx.workflows.start({ script: script("return await agent('never')"), parent }) + // No-reason cancel: the canonical default reason must ride the result. + first.cancel() + const firstResult = await first.result + expect(firstResult.stopReason).toBe('cancelled') + expect(firstResult.error).toContain('workflow cancelled') + expect(provider.runs.length).toBe(0) + await first.dispose() - it('the signal aborting mid-run cancels like cancel()', async () => { - const { ctx, parent, provider } = await setup({ manual: true }) const controller = new AbortController() - const handle = ctx.workflows.start({ script: script("return await agent('job')"), parent, signal: controller.signal }) + const second = ctx.workflows.start({ script: script("return await agent('job')"), parent, signal: controller.signal }) await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) controller.abort() - const result = await handle.result - expect(result.stopReason).toBe('cancelled') - await handle.dispose() + expect((await second.result).stopReason).toBe('cancelled') + await second.dispose() }) - it('reports a non-Error script throw (a thrown string) faithfully', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("throw 'plain string failure'")) - expect(result.stopReason).toBe('error') - expect(result.error).toContain('plain string failure') - }) - - it('a script Error surfaces its stack, carrying the script line numbers (lineOffset)', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("throw new Error('with stack')")) - expect(result.stopReason).toBe('error') - // Line 1 is the blanked meta statement; the throw sits on line 2. - expect(result.error).toContain('workflow:test-flow:2') - }) - - it('an object throw with neither stack nor message stringifies', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script('throw { code: 42 }')) - expect(result.stopReason).toBe('error') - expect(result.error).toBe('[object Object]') - }) - - it('falls back to the message for an Error whose stack was stripped', async () => { - const { ctx, parent } = await setup() - const result = await run(ctx, parent, script(` - const e = new Error('stackless failure') - e.stack = undefined - throw e - `)) - expect(result.stopReason).toBe('error') - expect(result.error).toBe('stackless failure') - }) - - it('cancel() in the same frame as start(): the awaited slot tick cannot start a child', async () => { + it('a child-start racing the host cancel is refused: no child starts after cancellation', async () => { const { ctx, parent, provider } = await setup({ manual: true }) - // agent() enters during start()'s synchronous slice and suspends on the - // acquireSlot await (one microtask tick even with a free slot); the - // synchronous cancel below lands in that tick. Without the post-acquire - // re-check the continuation would start a child carrying an ALREADY- - // aborted signal — which the stub provider (subscribing only to future - // abort events, like a real backend) would never settle, leaking it. - const handle = ctx.workflows.start({ script: script("return await agent('never')"), parent }) - handle.cancel('immediately after start') + // Cancel from INSIDE the log listener: the worker has already posted + // its child-start (queued right behind the log message), so the host + // processes it with cancelReason set — the refusal arm no real-world + // timing can hit reliably. (The closure runs only after `handle` below + // is initialized — the listener fires on the worker's first message.) + ctx.on('workflow/log', () => { handle.cancel('cancelled from the log listener') }) + const handle = ctx.workflows.start({ script: script("log('mark')\nreturn await agent('late')"), parent }) const result = await handle.result expect(result.stopReason).toBe('cancelled') expect(provider.runs.length).toBe(0) await handle.dispose() }) - it('a waiter resumed by a release RACING a cancel still dies at the post-acquire check', async () => { - const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 1 } }) + it('post-cancel narration is suppressed host-side, and completion racing a cancel reports cancelled', async () => { + const { ctx, parent } = await setup() + const narration: string[] = [] + ctx.on('workflow/log', (_info, message) => { narration.push(message) }) + ctx.on('workflow/phase', (_info, title) => { narration.push(`phase:${title}`) }) const handle = ctx.workflows.start({ - script: script("return await parallel([() => agent('a'), () => agent('b')])"), + // The sync spin keeps the worker's loop busy so the cancel message + // cannot be processed before the script settles `completed` — the + // worker posts a completed result that must LOSE to the in-flight + // host cancellation. The trailing narration exercises host-side + // suppression: posted pre-cancel-processing worker-side, arriving + // post-cancel host-side. + script: script(` + log('started') + const end = Date.now() + 1000 + while (Date.now() < end) {} + phase('late phase') + log('late log') + return 'done' + `), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) - // Same synchronous block: b is still a QUEUED waiter when the cancel - // lands, so cancel() rejects it outright; together with the immediate- - // cancel test above (the resumed-waiter tick), no post-cancel path can - // reach subagents.start. - provider.runs[0]!.settle(text('a-done')) - handle.cancel('raced') + await vi.waitFor(() => { expect(narration).toContain('started') }) + handle.cancel('raced the completion') const result = await handle.result expect(result.stopReason).toBe('cancelled') - expect(provider.runs.length).toBe(1) + expect(result.error).toContain('raced the completion') + expect(narration).toEqual(['started']) await handle.dispose() - }) + }, 15_000) - it('a dropped agent() promise cannot become an unhandled rejection when cancellation lands', async () => { - const unhandled: unknown[] = [] - const onUnhandled = (reason: unknown): void => { unhandled.push(reason) } - process.on('unhandledRejection', onUnhandled) - try { - const { ctx, parent, provider } = await setup({ manual: true }) - const handle = ctx.workflows.start({ - script: script(` - agent('dropped, never awaited') - return await agent('awaited') - `), - parent, - }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) - handle.cancel() - await handle.result - await handle.dispose() - // Let any stray rejection reach the process hook before asserting. - await new Promise(resolve => setTimeout(resolve, 20)) - expect(unhandled).toEqual([]) - } finally { - process.off('unhandledRejection', onUnhandled) - } - }) - - it('cancel() force-settles the result of a script parked on a promise no hook owns', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) - const ends: WorkflowResultInfo[] = [] - ctx.on('workflow/end', (_info, result) => { ends.push(result) }) + it('cancel() force-settles a script parked on a promise no hook owns, and TERMINATES its worker', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 50 } }) + const runEnds: WorkflowResultInfo[] = [] + ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) const handle = ctx.workflows.start({ - // No hooks involved: an unsettleable await cancellation cannot reject - // — the abandon grace is the only thing that can settle this run. script: script("await new Promise(() => {})\nreturn 'unreachable'"), parent, }) @@ -805,31 +374,20 @@ describe('dsh-workflow-vm', () => { expect(result.stopReason).toBe('cancelled') expect(result.error).toContain('user aborted') // The grace force-settle fires workflow/end exactly like an ordinary - // settlement — an abandoned script's death still reaches observers. - expect(ends).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: 0 }]) + // settlement — a terminated script's death still reaches observers. + expect(runEnds).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: 0 }]) await handle.dispose() }) - it('a never-settling returned thenable is abandoned the same way', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) - const handle = ctx.workflows.start({ script: script('return { then() {} }'), parent }) - handle.cancel() - expect((await handle.result).stopReason).toBe('cancelled') - await handle.dispose() - }) - - it('dispose() abandons a stuck script after the grace instead of hanging (result settles cancelled)', async () => { - const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 30 } }) + it('dispose() on a stuck script returns within the grace instead of hanging (result settles cancelled)', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 50 } }) const handle = ctx.workflows.start({ script: script("await new Promise(() => {})\nreturn 'unreachable'"), parent, }) const before = Date.now() await handle.dispose() - expect(Date.now() - before).toBeLessThan(1000) - // The abandon that freed dispose() also settled result — a consumer - // still awaiting it (the tool does, before its disposing finally) is - // released rather than wedged forever. + expect(Date.now() - before).toBeLessThan(2000) const result = await handle.result expect(result.stopReason).toBe('cancelled') }) @@ -842,25 +400,28 @@ describe('dsh-workflow-vm', () => { await handle.dispose() }) - it('strays: children fired without await are aborted once the script settles', async () => { - const { ctx, parent, provider } = await setup({ manual: true }) - const handle = ctx.workflows.start({ - script: script(` - agent('stray') - return 'done without awaiting' - `), - parent, - }) - const result = await handle.result - expect(result.stopReason).toBe('completed') - await vi.waitFor(() => { - expect(provider.runs.length).toBe(1) - expect(provider.runs[0]!.disposed).toBe(true) - }) - await handle.dispose() + it('a settled run arms NO grace timer: disposing a completed run must not pin it for disposeGraceMs', async () => { + // A distinctive grace so the spy can tell the cancel-path grace timer + // apart from every other timeout in flight. + const GRACE = 44_444 + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: GRACE } }) + const handle = ctx.workflows.start({ script: script('return 1'), parent }) + await handle.result + const spy = vi.spyOn(globalThis, 'setTimeout') + try { + await handle.dispose() + // dispose()'s own bounded-wait sleep is the ONLY grace-sized timer + // allowed here; before the settled guard, cancel() armed a second one + // that nothing would ever clear (the run was already settled), keeping + // the WorkerRun/Worker closure alive until the grace expired. + const graceTimers = spy.mock.calls.filter(call => call[1] === GRACE) + expect(graceTimers.length).toBe(1) + } finally { + spy.mockRestore() + } }) - it('dispose() waits for a stray child to FINISH disposing (quiescence), not just the script settle', async () => { + it('strays: children fired without await are aborted once the script settles, and dispose() waits for their disposal', async () => { const { ctx, parent, provider } = await setup({ manual: true, disposeDelayMs: 40 }) const handle = ctx.workflows.start({ script: script(` @@ -871,12 +432,222 @@ describe('dsh-workflow-vm', () => { }) const result = await handle.result expect(result.stopReason).toBe('completed') - expect(provider.runs.length).toBe(1) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) await handle.dispose() // Not a waitFor: by the time dispose() returns, the slow child disposal - // must already be complete. + // must already be complete (host-side registry quiescence). expect(provider.runs[0]!.disposed).toBe(true) }) + + it('the settle-reap fires the request signal too: a provider honoring ONLY the signal winds its stray down promptly', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + const aborted: string[] = [] + const provider: SubagentProvider = { + name: 'signal-only', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + inheritsParentContext: false, + start: (request) => { + let settle!: (result: SubagentResult) => void + const result = new Promise((resolve) => { settle = resolve }) + request.signal?.addEventListener('abort', () => { + aborted.push(String(request.signal?.reason)) + settle({ output: [], stopReason: 'aborted' }) + }, { once: true }) + return { + id: AgentId('signal-only-child'), + result, + // The seam leaves a provider free to honor EITHER cancel channel; + // this one deliberately ignores run.cancel() — only the request + // signal can wind it down. + cancel: () => { /* signal-only by design */ }, + dispose: () => Promise.resolve(), + } + }, + } + ctx.subagents.registerProvider(provider) + await ctx.plugin(WorkerWorkflowEngine, { provider: 'signal-only', maxConcurrentAgents: 2 }) + const handle = ctx.workflows.start({ + script: script(` + agent('stray, never awaited') + return 'done' + `), + parent: fakeParent(), + }) + const result = await handle.result + expect(result.stopReason).toBe('completed') + // BEFORE dispose(): the settlement itself must have aborted the signal — + // without it this child would stay live until dispose's terminate. + await vi.waitFor(() => { expect(aborted).toEqual(['workflow settled']) }) + await handle.dispose() + }) + + it("cancel() drives each child's explicit cancel() host-side: a wedged worker cannot delay it", async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + let starts = 0 + const cancelled: string[] = [] + const provider: SubagentProvider = { + name: 'cancel-only', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + inheritsParentContext: false, + start: () => { + starts += 1 + return { + id: AgentId('cancel-only-child'), + result: new Promise(() => { /* only cancel() ends this child */ }), + // Deliberately ignores the request signal — the seam leaves a + // provider free to honor ONLY the explicit cancel() channel. + cancel: (reason?: string) => { cancelled.push(reason ?? 'cancelled') }, + dispose: () => Promise.resolve(), + } + }, + } + ctx.subagents.registerProvider(provider) + // A deliberately huge grace: if only the grace/terminate reap could + // reach this child, the assertion below would time out first. + await ctx.plugin(WorkerWorkflowEngine, { provider: 'cancel-only', maxConcurrentAgents: 2, disposeGraceMs: 30_000 }) + const handle = ctx.workflows.start({ + // The stray child's start RPC reaches the host, then the script wedges + // its own worker in a synchronous spin: the worker cannot process the + // Cancel message, so it can relay NO ChildCancel RPC — only the host's + // own children loop can deliver the explicit cancel in time. + script: script(` + agent('wedged child') + const end = Date.now() + 1500 + while (Date.now() < end) {} + return 'raced' + `), + parent: fakeParent(), + }) + await vi.waitFor(() => { expect(starts).toBe(1) }) + handle.cancel('stop now') + await vi.waitFor(() => { expect(cancelled).toEqual(['stop now']) }, { timeout: 800 }) + // The wedged worker's own completion loses to the in-flight cancel. + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + await handle.dispose() + }, 15_000) + }) + + describe('worker death', () => { + it('a worker that exits before settling reports an error result and reaps its children', async () => { + const ctx = new Context() + await ctx.plugin(SubagentService) + // The child's dispose() REJECTS on top of the worker death: the reap + // must contain it (warn, not crash) while still emptying the registry. + const cancelled: string[] = [] + const provider: SubagentProvider = { + name: 'doomed', + capabilities: { outputSchema: true, depthLimit: true, toolFilter: true }, + inheritsParentContext: false, + start: () => ({ + id: AgentId('doomed-child'), + result: new Promise(() => { /* never settles; the reap is the teardown */ }), + cancel: (reason?: string) => { cancelled.push(reason ?? 'cancelled') }, + dispose: () => Promise.reject(new Error('dispose exploded during reap')), + }), + } + ctx.subagents.registerProvider(provider) + await ctx.plugin(WorkerWorkflowEngine, { provider: 'doomed', maxConcurrentAgents: 2 }) + const runEnds: WorkflowResultInfo[] = [] + ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) + const handle = ctx.workflows.start({ + // The stray child's start RPC reaches the host, then the script kills + // its own worker through the documented vm escape — the host must + // settle `error` with the exit diagnostics and wind the child down. + script: script(` + agent('doomed') + const proc = ${ESCAPE} + const st = globalThis.constructor.constructor('return setTimeout')() + await new Promise(resolve => st(resolve, 200)) + proc.exit(7) + `), + parent: fakeParent(), + }) + const result = await handle.result + expect(result.stopReason).toBe('error') + expect(result.error).toContain('exit code 7') + expect(result.agentsStarted).toBe(1) + // A worker death is a stop reason like any other: workflow/end fires + // with the error outcome — for a bus observer it is the only obituary. + expect(runEnds).toEqual([{ stopReason: 'error', error: result.error, agentsStarted: 1 }]) + await vi.waitFor(() => { expect(cancelled.length).toBe(1) }) + await handle.dispose() + }, 15_000) + + it('an uncaught exception inside the worker surfaces as an error result and reaps the in-flight child', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + script: script(` + agent('in flight when the worker dies') + const proc = ${ESCAPE} + const st = globalThis.constructor.constructor('return setTimeout')() + await new Promise(resolve => st(resolve, 200)) + proc.nextTick(() => { throw new Error('worker blew up') }) + await new Promise(() => {}) + `), + parent, + }) + const result = await handle.result + expect(result.stopReason).toBe('error') + expect(result.error).toContain('worker blew up') + // The reap wound the stray child down (cancel + a CLEAN dispose). + await vi.waitFor(() => { + expect(provider.runs.length).toBe(1) + expect(provider.runs[0]!.disposed).toBe(true) + }) + await handle.dispose() + }, 15_000) + + it('a dispose ack racing the worker death is dropped, not crashed (post after exit)', async () => { + // Slow child disposal: the ack resolves only AFTER the worker died, so + // it has nowhere to go and must be dropped silently (the workerGone + // guard in post()). + const { ctx, parent, provider } = await setup({ disposeDelayMs: 300 }) + const handle = ctx.workflows.start({ + // The STRAY child settles instantly, so its wrapper starts the slow + // host-side disposal concurrently while the script goes on to kill + // its own worker — the ack then resolves into a dead thread. + script: script(` + agent('stray, never awaited') + const proc = ${ESCAPE} + const st = globalThis.constructor.constructor('return setTimeout')() + await new Promise(resolve => st(resolve, 150)) + proc.exit(5) + `), + parent, + }) + const result = await handle.result + expect(result.stopReason).toBe('error') + expect(result.error).toContain('exit code 5') + await vi.waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }) + await handle.dispose() + }, 15_000) + + it('a worker death AFTER a cancel reports cancelled, not error', async () => { + const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 60_000 } }) + const handle = ctx.workflows.start({ + script: script(` + const proc = ${ESCAPE} + const st = globalThis.constructor.constructor('return setTimeout')() + log('armed') + await new Promise(resolve => st(resolve, 400)) + proc.exit(3) + `), + parent, + }) + const logs: string[] = [] + ctx.on('workflow/log', (_info, message) => { logs.push(message) }) + await vi.waitFor(() => { expect(logs).toContain('armed') }) + handle.cancel('stop it') + // The grace is deliberately huge: only the worker's own death (exit 3, + // unreachable by the cancel — the script ignores hooks) settles this. + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('stop it') + await handle.dispose() + }, 15_000) }) describe('service surface', () => { @@ -887,7 +658,6 @@ describe('dsh-workflow-vm', () => { const first = ctx.workflows.start({ script: script('return 1'), parent }) const second = ctx.workflows.start({ script: script('return 2'), parent }) expect(first.id).not.toBe(second.id) - // Mutating a listener's snapshot cannot corrupt the holder's view. eventMeta!.meta.name = 'corrupted' expect(second.meta.name).toBe('test-flow') await Promise.all([first.result, second.result]) @@ -895,38 +665,24 @@ describe('dsh-workflow-vm', () => { await second.dispose() }) - it('a listener mutating one event payload cannot corrupt later events (per-emission snapshots)', async () => { - const { ctx, parent } = await setup() - const ends: unknown[] = [] - let endInfo: WorkflowRunInfo | undefined - ctx.on('workflow/agent-start', (info, agent) => { - agent.seq = 999 - agent.label = 'HACKED' - info.meta.name = 'HACKED' - }) - ctx.on('workflow/agent-end', (info, agent) => { - ends.push(agent) - endInfo = info - }) - await run(ctx, parent, script("return await agent('job', { label: 'honest' })")) - expect(ends[0]).toMatchObject({ seq: 1, label: 'honest', outcome: 'completed' }) - expect(endInfo!.meta.name).toBe('test-flow') - }) - - it('unregisters ctx.workflows when the engine fiber is disposed (HMR safety)', async () => { + it('unregisters ctx.workflows when the engine fiber is disposed (HMR safety), and default config runs (auto concurrency)', async () => { const ctx = new Context() await ctx.plugin(SubagentService) - const fiber = await ctx.plugin(VmWorkflowEngine, {}) + const fiber = await ctx.plugin(WorkerWorkflowEngine, {}) expect(ctx.get('workflows')).toBeDefined() + // A zero-agent run through the DEFAULT config exercises the auto + // concurrency resolution (cores - 2, capped) in start(). + const result = await run(ctx, fakeParent(), script('return 6 * 7')) + expect(result.value).toBe(42) await fiber.dispose() expect(ctx.get('workflows')).toBeUndefined() }) it('has the class-plugin export shape (default = the engine service class)', () => { - expect(vmEngineModule.default).toBe(VmWorkflowEngine) + expect(workerEngineModule.default).toBe(WorkerWorkflowEngine) const loader = Object.create(Loader.prototype) as Loader - const unwrapped: unknown = loader.unwrapExports(vmEngineModule) - expect(unwrapped).toBe(VmWorkflowEngine) + const unwrapped: unknown = loader.unwrapExports(workerEngineModule) + expect(unwrapped).toBe(WorkerWorkflowEngine) }) }) }) diff --git a/packages/workflow/workflow-vm/tests/workflow.e2e.ts b/packages/workflow/workflow-vm/tests/workflow.e2e.ts index c3f959d072..76cfd73d33 100644 --- a/packages/workflow/workflow-vm/tests/workflow.e2e.ts +++ b/packages/workflow/workflow-vm/tests/workflow.e2e.ts @@ -9,16 +9,14 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' import SubagentService from '@deepseek-ai/dsh-subagent' import * as Spawn from '@deepseek-ai/dsh-subagent-spawn' -import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow' -import { CallId } from '@deepseek-ai/dsh-llm' -import VmWorkflowEngine from '../src/index.ts' +import WorkerWorkflowEngine from '../src/index.ts' /** - * With-key e2e for the workflow engine: a REAL script drives REAL spawn - * children against the live DeepSeek API — one plain child and one schema'd - * child through the real structured-output runtime — and the run's value, - * events, and child sessions are asserted from the outside (never the - * script's self-report alone). Key-gated (self-skips without + * With-key e2e: a REAL script in a REAL worker thread + * drives REAL spawn children against the live DeepSeek API — one plain child + * and one schema'd child through the real structured-output runtime — and + * the run's value, events, and child sessions are asserted from the outside + * (never the script's self-report alone). Key-gated (self-skips without * DEEPSEEK_API_KEY). */ @@ -40,14 +38,13 @@ async function harness(): Promise { await built.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] }) await built.plugin(SubagentService) await built.plugin(Spawn, { providerName: 'spawn' }) - await built.plugin(VmWorkflowEngine, { provider: 'spawn' }) - await built.plugin(ToolWorkflow, {}) + await built.plugin(WorkerWorkflowEngine, { provider: 'spawn' }) return built } const SCRIPT = `export const meta = { - name: 'e2e-arithmetic', - description: 'two real children: one prose, one structured', + name: 'e2e-worker-arithmetic', + description: 'two real children through a worker thread: one prose, one structured', phases: [{ title: 'Ask' }, { title: 'Judge' }], } phase('Ask') @@ -61,12 +58,12 @@ const judged = await agent( ) return { prose, containsFour: judged === null ? null : judged.containsFour }` -describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workflow engine with-key e2e', () => { - it('runs a two-phase script over real children, one through the structured runtime', async () => { +describe.skipIf(!process.env.DEEPSEEK_API_KEY)('worker workflow engine with-key e2e', () => { + it('runs a two-phase script in a worker thread over real children, one through the structured runtime', async () => { ctx = await harness() const parentHandle = ctx.agents.create({ - agentId: AgentId('wf-e2e-parent'), - sessionId: 'wf-e2e-session' as never, + agentId: AgentId('wf-worker-e2e-parent'), + sessionId: 'wf-worker-e2e-session' as never, agentOptions: { model: 'deepseek-v4-flash' }, }) @@ -102,30 +99,4 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workflow engine with-key e2e', ( } await parentHandle.dispose() }, 240_000) - - it('the workflow TOOL runs the same path through the real registry pipeline', async () => { - ctx = await harness() - const parentHandle = ctx.agents.create({ - agentId: AgentId('wf-e2e-tool-parent'), - sessionId: 'wf-e2e-tool-session' as never, - agentOptions: { model: 'deepseek-v4-flash' }, - }) - - const result = await ctx.tools.execute({ - callId: CallId('wf-e2e-call'), - name: 'workflow', - arguments: { - script: `export const meta = { name: 'e2e-tool', description: 'one real child via the tool' } -const answer = await agent('Reply with exactly one word: the capital of France.') -return { answer }`, - }, - agent: parentHandle.agent, - }) - - expect(result.isError).toBe(false) - const text = (result.content[0] as { text: string }).text - expect(text).toContain('workflow "e2e-tool" completed (1 agent)') - expect(text.toLowerCase()).toContain('paris') - await parentHandle.dispose() - }, 240_000) }) diff --git a/packages/workflow/workflow-vm/tsdown.config.ts b/packages/workflow/workflow-vm/tsdown.config.ts new file mode 100644 index 0000000000..3102a36c1c --- /dev/null +++ b/packages/workflow/workflow-vm/tsdown.config.ts @@ -0,0 +1,32 @@ +import { defineConfig } from 'tsdown' + +/** + * The engine ships two runtime entries: the engine service (index) and the + * worker-thread entry (worker) the engine spawns via `new Worker`. The + * entries are JS emitted by tsc under lib/types and are bundled as two + * single-entry passes so shared modules (realm, runtime, session) are inlined + * into each instead of split into a hash-named chunk (the worker entry must + * be a self-contained file the Worker constructor can load by path). + */ +export default defineConfig([ + { + entry: ['lib/types/index.js'], + outDir: 'lib', + format: ['esm'], + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: false, + }, + { + entry: ['lib/types/worker.js'], + outDir: 'lib', + format: ['esm'], + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: false, + }, +]) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f236c67bf2..e3e1892e35 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1159,6 +1159,9 @@ importers: cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + tsx: + specifier: ^4.19.2 + version: 4.22.4 vendor/cordis: dependencies: diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts index f579169ab0..2d12a66d8f 100644 --- a/scripts/check-workspace-constraints.ts +++ b/scripts/check-workspace-constraints.ts @@ -105,12 +105,25 @@ const dshBinPackageFiles = [ 'src', ] as const +const dshWorkerPackageFiles = [ + 'lib/index.js', + 'lib/worker.js', + 'lib/types/**/*.d.ts', + 'lib/types/**/*.d.ts.map', + 'src', +] as const + function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean { return !!actual && actual.length === expected.length && actual.every((value, index) => value === expected[index]) } function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] { - return manifest.bin ? dshBinPackageFiles : dshPackageFiles + if (manifest.bin) return dshBinPackageFiles + // A declared "./worker" subpath export sanctions the one extra runtime + // bundle a worker-thread entry needs (and NodeNext/publint then validate + // that subpath's targets like any other export). + if (manifest.exports?.['./worker']) return dshWorkerPackageFiles + return dshPackageFiles } function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] { diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 6c844f842a..25e08cf8d2 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -310,6 +310,10 @@ function builtBinSmokeGate(): Gate { 'vitest.e2e.config.ts', 'packages/ui/stdio-agent/tests/built-bin.e2e.ts', 'packages/ui/acp-agent/tests/built-bin.e2e.ts', + // The workflow engine's built worker bundle: the only automated proof + // that lib/index.js resolves its sibling lib/worker.js under plain node + // (the e2e lane runs unbuilt, so this file self-skips there). + 'packages/workflow/workflow-vm/tests/built-worker.e2e.ts', ], { label: 'built-bin smoke', needs: ['build'], From d5c65e2b4c52271c9fb1a895b64d5457793bdd4c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 18:50:29 +0800 Subject: [PATCH 098/119] docs: describe the workflow engine as worker-thread first The outer ring catches up with the engine swap (the package's own README/JSDoc rode the port commit): - Seam module doc and README name the worker-thread engine as THE implementation, with isolated-vm/separate-process sandboxing as the deferred hardening; the seam service doc states the holder-owned-runs contract (engine-fiber disposal deliberately leaves live runs to their holders). - Seam contract precision: agentsStarted documents the termination-path degradation to the host-observed count; the events section scopes the agent-start/agent-end pair to calls that STARTED a child run; WorkflowRun wording drops the vm-era abandonment language. - The dynamic-workflows RFC is rewritten in place to the shipped mechanism (implemented-RFC rule): why worker threads, the thread's concrete buys, the in-process node:vm first cut recorded under alternatives considered; the tool section describes the usage policy as the tool's own prompt section. - gen-doc-graphs: six workflow/* DYNAMIC_EVENT_DISPATCHERS entries (the catalog no longer claims nothing dispatches them) and the seam-note wording; core-data-structures gains its workflow.md index row; packages/README + AGENTS.md layout line + example cordis.yml comments say worker-thread; catalogs regenerated. --- AGENTS.md | 2 +- docs/capability-seams.md | 2 +- docs/config-catalog.md | 8 +++---- docs/cordis-catalog/services.md | 3 ++- docs/core-data-structures/core.md | 1 + docs/core-data-structures/workflow.md | 4 ++-- docs/event-producer-consumer.md | 12 +++++------ .../feature/2026-07-05-dynamic-workflows.md | 17 ++++++++------- examples/acp-agent/cordis.yml | 8 +++---- examples/coding-agent/cordis.yml | 8 +++---- packages/README.md | 2 +- packages/workflow/README.md | 4 ++-- packages/workflow/workflow/README.md | 6 +++--- packages/workflow/workflow/src/index.ts | 13 ++++++++---- packages/workflow/workflow/src/types.ts | 21 ++++++++++++------- scripts/gen-doc-graphs.ts | 10 ++++++++- 16 files changed, 72 insertions(+), 49 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eb34d404a0..5602b244ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai web/ web seam + search/fetch providers + model-facing web tools compact/ compaction seam + basic backend subagent/ subagent seam + spawn/fork/ACP backends + delegation tool - workflow/ workflow seam + node:vm script engine + the workflow tool + workflow/ workflow seam + worker-thread script engine + the workflow tool todo/ the todo_write tool hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends diff --git a/docs/capability-seams.md b/docs/capability-seams.md index caa9905e46..1a13bd2060 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -145,6 +145,6 @@ flowchart LR | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. | | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. | -| `ctx.workflows` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-vm`](../packages/workflow/workflow-vm) | [`tool-workflow`](../packages/workflow/tool-workflow) | - | One engine per context (bash shape, no named-provider registry); the vm engine fans agent() calls out through ctx.subagents. | +| `ctx.workflows` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-vm`](../packages/workflow/workflow-vm) | [`tool-workflow`](../packages/workflow/tool-workflow) | - | One engine per context (bash shape, no named-provider registry); the worker-thread engine fans agent() calls out through ctx.subagents. | Maintenance mode: hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard. diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 8ffaefdabd..300468dd70 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -815,18 +815,18 @@ export interface Config { maxTotalAgents?: number /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */ maxItemsPerCall?: number - /** vm timeout for the script's initial synchronous slice AND the meta-literal evaluation (default 5000 ms). */ + /** vm timeout for the initial synchronous slice (inside the worker) AND the host-side meta evaluation (default 5000 ms). */ syncTimeoutMs?: number /** * How long after a cancellation an unsettled script may keep running before - * it is abandoned and `result` force-settles `cancelled` (default 5000 ms); - * also bounds `dispose()`. + * the run force-settles `cancelled` and its worker is TERMINATED (default + * 5000 ms); also bounds `dispose()`. */ disposeGraceMs?: number } ``` -Source: [`packages/workflow/workflow-vm/src/index.ts:58`](../packages/workflow/workflow-vm/src/index.ts) +Source: [`packages/workflow/workflow-vm/src/index.ts:69`](../packages/workflow/workflow-vm/src/index.ts) ## Loadable plugins with no config diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 027fa054c1..13c9f57733 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -238,12 +238,13 @@ Semantics every implementation must honor: - start throws synchronously for a request that cannot begin (an unparseable script, an invalid meta block). Once it returns a WorkflowRun, `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` SETTLES within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). - The `workflow/*` events fire through emitWorkflowEvent (data snapshots, per-listener containment); `workflow/end` fires exactly once per started run, after `result` is settled or as it settles. - `dispose()` reaches quiescence within a bounded grace: it cancels, waits for the script to settle AND its started children to finish disposing, and abandons whatever is left rather than hanging its caller (the engine documents what abandonment leaves behind). +- Runs are HOLDER-OWNED: the engine hands control (`cancel`/`dispose`) to the `start()` caller and does not track its live runs — disposing the engine's own fiber mid-run deliberately leaves those runs to their holders' teardown, so an engine reload cannot yank a run out from under the consumer awaiting it. ```ts cordis-catalog abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Source: [`packages/workflow/workflow/src/index.ts:202`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:207`](../../packages/workflow/workflow/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 7d1110d7a8..2f1e5031e9 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -24,6 +24,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface | | [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split | | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider/capability status, `WebError` | +| [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality | > Type definitions on this page are pasted **verbatim** from source and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Inline JSDoc is omitted for readability; follow the source link for the full contracts. diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md index 8c7916a6c3..4d880ea948 100644 --- a/docs/core-data-structures/workflow.md +++ b/docs/core-data-structures/workflow.md @@ -2,7 +2,7 @@ The workflow seam — an agent running a model-written orchestration SCRIPT that fans out subagents. Like [subagent](subagent.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). Unlike the subagent registry it takes the bash shape: ONE engine implementation per context provides `ctx.workflows`; there is no named-provider registry (a second engine is a plugin swap, not a co-resident). -Interface: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The implementation is [dsh-workflow-vm](../../packages/workflow/workflow-vm) (an in-process `node:vm` engine); the model-facing consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows RFC](../rfc/implemented/feature/2026-07-05-dynamic-workflows.md). +Interface: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The implementation is [dsh-workflow-vm](../../packages/workflow/workflow-vm) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows RFC](../rfc/implemented/feature/2026-07-05-dynamic-workflows.md). Source: [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts) @@ -47,7 +47,7 @@ interface WorkflowResult { ## A live run: `WorkflowRun` -The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — and once the run is cancelled it SETTLES within the engine's bounded grace even if the script itself never settles (the engine abandons the script and reports `cancelled`), so a consumer awaiting `result` is never wedged past a cancellation. `dispose()` = cancel + that bounded settle + child quiescence (the engine documents what abandonment leaves behind); it never hangs on a stuck script. +The handle the consumer holds while a script executes. The consumer awaits `result`, may `cancel` mid-flight, and MUST `dispose` on every path. `result` does NOT reject — a script failure resolves with `stopReason: 'error'` — and once the run is cancelled it SETTLES within the engine's bounded grace even if the script itself never settles (the engine force-settles `cancelled`; the worker-thread engine then terminates the script's worker), so a consumer awaiting `result` is never wedged past a cancellation. `dispose()` = cancel + that bounded settle + child quiescence; it never hangs on a stuck script. ```ts type-equiv interface WorkflowRun { diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index ec1fc468e3..a8618022a5 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -34,11 +34,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:76`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:93`](../packages/workflow/workflow/src/index.ts) | - | - | -| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:85`](../packages/workflow/workflow/src/index.ts) | - | - | -| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:103`](../packages/workflow/workflow/src/index.ts) | - | - | -| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:77`](../packages/workflow/workflow/src/index.ts) | - | - | -| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | - | - | -| `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:62`](../packages/workflow/workflow/src/index.ts) | - | - | +| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:93`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:85`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:103`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:77`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:62`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`. diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index f7749efa56..d0e436b17e 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -20,19 +20,19 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre `ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [core-data-structures/workflow.md](../../../core-data-structures/workflow.md). -### The engine (dsh-workflow-vm): in-process node:vm +### The engine (dsh-workflow-vm): one worker thread per run -**Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) AND Node-API escape from the context — the vm context shares object machinery with the host, so a script can reach the host `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin; the absent globals are API surface, not containment. Host code MAY run script code while reading script values, and that is accepted, because a hostile script can already occupy the event loop forever with a synchronous spin past its first await; containing its error VALUES while conceding it the event loop would be cost without a threat model. Genuine hardening is an engine swap behind the seam (worker/isolated-vm gets value isolation by serialization for free), not incremental host-side defenses. +**Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) AND Node-API escape from the script's context — the vm context shares object machinery with its surrounding realm, so a script can reach the `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin; the absent globals are API surface, not containment, and a worker thread is NOT a security boundary (an escapee holds process-wide privileges — Node's permission model is per-process). Worker-side code MAY run script code while reading script values, and that is accepted: a synchronous spin costs the script its OWN thread (terminated at the post-cancel grace), never the host loop, so containing error VALUES would be cost without a threat model. Genuine sandboxing (isolated-vm, a separate process) remains an engine swap behind the seam, not incremental defenses here. -**Why node:vm and not isolated-vm/worker threads**: isolated-vm is in maintenance mode, needs `--no-node-snapshot` on EVERY consumer process (including the published bins) on Node ≥ 20, and falls back to node-gyp source builds; a worker-thread engine turns every hook into RPC and complicates the per-file coverage gate. Under the trust premise, in-process is enough. Accepted, documented limitations: `start()` blocks the caller for the script's initial synchronous slice (bounded by the vm timeout); that timeout covers ONLY the initial slice, so a synchronous spin past it (an await continuation, a thenable's `then` invoked by promise resolution — a returned thenable resolves per JavaScript semantics, which is what makes an un-awaited `return agent('x')` work — or script code the host runs while rendering a thrown value) cannot be killed in-process; `dispose()` cancels, waits a bounded grace for the script to settle and its children to finish disposing, then abandons. +**Why node:worker_threads**: one run = one worker thread, no pooling — a run is heavyweight (many children), so thread spin-up (~tens of ms) is noise. The script runs in a vm context INSIDE the worker, keeping the script-visible surface exactly the hook contract above (a bare worker realm would leak `setTimeout`/`fetch`/`process` as accidental API), and every `agent()` bridges to `ctx.subagents` by message-port RPC — children are I/O-bound LLM loops and stay on the host loop; the thread isolates the SCRIPT, the only part that can spin. What the thread buys: `start()` never blocks the host (an in-process engine runs the initial synchronous slice inline and cannot kill a spin past the first await — it could only ABANDON such a script, leaving the spin on the host loop), the post-cancel grace ends in a REAL `worker.terminate()`, and the value boundary is serialization by construction. isolated-vm was rejected for actual sandboxing: maintenance mode, `--no-node-snapshot` on EVERY consumer process (including published bins) on Node ≥ 20, node-gyp source-build fallback. Key mechanics (details in the package README): meta extraction and a body pre-parse stay HOST-side (preserving the seam's synchronous throws), a ready→go handshake keeps a run cancelled before start from ever executing the body, `cancel()` drives both child-cancel channels host-side (the shared request signal AND each child's explicit `cancel()` — a wedged worker cannot relay its own cancel RPCs), a host-side child registry backs worker-death reaping and `dispose()` quiescence, the wire protocol is enum-keyed payload maps private to the package, and on a termination path `agentsStarted` degrades to the host-observed count. Coverage puts the worker-side session on an in-process `MessageChannel` (real-Worker code is invisible to main-process v8) and proves the built `lib/worker.js` — a second tsdown entry, sanctioned in the workspace-constraints gate by the `"./worker"` subpath export — under plain node in the built-bin smoke gate. **Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. -**Value boundary**: values entering the host (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation; getters are read ordinarily and their RESULT crosses (a throwing read fails loud). Values entering the realm (`args`, `agent()` results, hook promises and failures, combinator arrays) are handed over directly as host values — the script is trusted, so host prototypes are not a leak; `args` is host-`structuredClone`d once so a script cannot mutate the caller's object. Hook failures are host `WorkflowError`s: the combinators recognize fatality by host `instanceof` (unforgeable from the realm), and the script-visible consequence — in-script `instanceof Error` is `false` for hook errors; branch on `e.name`/`e.code` — is documented in the engine README. Realm functions (stages, thunks) are called, never materialized. Thrown script values are rendered by a total host-side renderer (stack → message → `String()`, fixed label if rendering throws), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, max(1, availableParallelism() - 2))`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. +**Value boundary**: values leaving the script (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation; getters are read ordinarily and their RESULT crosses (a throwing read fails loud) — which is also what makes every later postMessage hop total. Values entering the realm (`args`, `agent()` results, hook promises and failures, combinator arrays) are handed over directly as worker-realm values — the script is trusted, so outer prototypes are not a leak; `args` rides the `workerData` structured clone (the caller-isolation copy) and is cloned once more so a script scribbling on it cannot mutate the session's init object. Hook failures are `WorkflowError`s built OUTSIDE the script's context: the combinators recognize fatality by `instanceof` against the engine's own class (unforgeable from the script), and the script-visible consequence — in-script `instanceof Error` is `false` for hook errors; branch on `e.name`/`e.code` — is documented in the engine README. Realm functions (stages, thunks) are called, never materialized. Thrown script values are rendered by a total renderer (stack → message → `String()`, fixed label if rendering throws), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, max(1, availableParallelism() - 2))`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. ### The consumer (dsh-tool-workflow) -A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by a textual `meta.name` sniff (presentation is a pure function of args). The tool description IS the model-facing authoring spec. Examples load it with guidance to use workflows only on explicit user request — the harness has no ultracode-style effort gate. +A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by a textual `meta.name` sniff (presentation is a pure function of args). The tool description IS the model-facing authoring spec. The usage policy ships with the tool as its own `tool:` prompt section (explicit-ask-only guidance — tool guidance lives in tool plugins, never in the deployment persona); the harness has no ultracode-style effort gate. ### The foundation: structured output on the subagent seam @@ -45,13 +45,14 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai - **Saved/bundled workflows** (a `.deepseek/workflows/` registry, slash-command surface) and **script persistence to a run directory** (the tool-call event already records the script durably). - **Nested `workflow()`**, **token `budget`**, and the `effort`/`isolation`/`agentType` agent options (each rejects loud with a message naming it deferred). - **An overall run wall-clock timeout** — cancellation always frees the caller (result settles within the grace), so a cap on total run time is a policy knob for the background redesign, not a correctness need here. -- **Engine hardening**: a worker-thread or isolated-vm engine behind the same seam (kills synchronous spins; adds memory limits). +- **Engine hardening beyond worker threads**: an isolated-vm or separate-process engine behind the same seam (actual sandboxing; memory limits). - **ACP progress UI** over the `workflow/*` events (a `/workflows`-style view); the events exist for it. - **ACP-backend structured output** and **`toolFilter`** (both still capability-gated `false`). ## Alternatives considered -- **Hostile-value containment in the host** (trap-free proxy rejection, accessor-never-invoked descriptor walks, realm-side pre-rendering of thrown values, realm-built promises/arrays/error clones with structural fatal recognition): an earlier revision built all of it, and review showed the cost was real while the threat model was not — every one of those defenses guards against an author the premise already trusts, who retains an accepted unkillable event-loop spin regardless. Removed in favor of the plain boundary above; the hardened engine deletes such machinery anyway (serialization by construction). +- **Hostile-value containment in the host** (trap-free proxy rejection, accessor-never-invoked descriptor walks, realm-side pre-rendering of thrown values, realm-built promises/arrays/error clones with structural fatal recognition): an earlier revision built all of it, and review showed the cost was real while the threat model was not — every one of those defenses guards against an author the premise already trusts. Removed in favor of the plain boundary above; the thread boundary makes such machinery redundant anyway (serialization by construction). +- **In-process `node:vm` execution** (the first cut of this RFC shipped it): mechanically simplest — no RPC, no thread — but `start()` blocks the caller for the script's initial synchronous slice, a synchronous spin past the first await cannot be killed in-process (the vm `timeout` covers only that first slice), and `dispose()` could only ABANDON an unsettling script, leaving the spin on the host loop. Superseded by the worker-thread engine, which keeps the same vm-context script surface while unblocking the host and making termination real. - **Background execution as the default** (CC's shape): deferred; foreground-synchronous matches `dsh-tool-subagent`'s cut, and background semantics should be designed ONCE across bash/subagent/workflow rather than per-tool. - **Workflow-layer JSON parsing for `agent({schema})`**: duplicating a seam concern at one consumer while the seam's capability flag stayed dishonestly `false`. - **Meta as tool parameters instead of `export const meta`**: zero parsing, but scripts stop being self-contained artifacts and CC-authored scripts stop being drop-in. @@ -62,4 +63,4 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai ## Consequences -The harness gains CC-compatible script orchestration: fan-out plans live in a rerunnable artifact instead of the parent context, and the structured-output half of the subagent seam is now real (the vocabulary stopped lying about `outputSchema`). What it cost, all bounded by the trust premise: the in-process engine blocks its caller for a script's initial synchronous slice, cannot kill a synchronous spin past that slice, and does not isolate host values from the script — acceptable because scripts share the model's trust level, and each limitation names its exit (the engine swap behind the seam). The fatal-vs-null strictness divergence from CC means a CC-authored script that RELIES on option typos dissolving to `null` behaves differently here — judged worth it to keep the repo's no-accepted-then-ignored rule. Consumers must hold the run handle for control (`cancel`/`dispose`); observers get data snapshots only, so no listener can extend a run's lifetime or corrupt another's view. +The harness gains CC-compatible script orchestration: fan-out plans live in a rerunnable artifact instead of the parent context, and the structured-output half of the subagent seam is now real (the vocabulary stopped lying about `outputSchema`). What it cost, all bounded by the trust premise: a worker thread per run (~tens-of-ms spin-up), every hook crossing a message port as RPC, and a termination-path `agentsStarted` that degrades to the host-observed count; in exchange `start()` never blocks the host, a post-cancel grace ends in a real `worker.terminate()`, and the value boundary is serialization by construction. A worker thread is still NOT a security boundary — scripts share the model's trust level, and actual sandboxing names its exit (the isolated-vm/separate-process engine swap behind the seam). The fatal-vs-null strictness divergence from CC means a CC-authored script that RELIES on option typos dissolving to `null` behaves differently here — judged worth it to keep the repo's no-accepted-then-ignored rule. Consumers must hold the run handle for control (`cancel`/`dispose`); observers get data snapshots only, so no listener can extend a run's lifetime or corrupt another's view. diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml index eeb78a7962..f2015bc7c2 100644 --- a/examples/acp-agent/cordis.yml +++ b/examples/acp-agent/cordis.yml @@ -82,10 +82,10 @@ toolName: subagent_fork -# Dynamic workflows: the node:vm engine (ctx.workflows) over the spawn subagent -# backend above, plus the model-facing `workflow` tool. The model writes a -# JavaScript orchestration script (meta + body); the engine runs it in-process -# and fans agent() calls out as spawn children. +# Dynamic workflows: the worker-thread engine (ctx.workflows) over the spawn +# subagent backend above, plus the model-facing `workflow` tool. The model +# writes a JavaScript orchestration script (meta + body); the engine runs it +# in its own worker thread and fans agent() calls out as spawn children. - id: workflow-vm name: '@deepseek-ai/dsh-workflow-vm' config: diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml index 28643e0d73..ee55bced0b 100644 --- a/examples/coding-agent/cordis.yml +++ b/examples/coding-agent/cordis.yml @@ -103,10 +103,10 @@ toolName: subagent_fork -# Dynamic workflows: the node:vm engine (ctx.workflows) over the spawn subagent -# backend above, plus the model-facing `workflow` tool. The model writes a -# JavaScript orchestration script (meta + body); the engine runs it in-process -# and fans agent() calls out as spawn children. +# Dynamic workflows: the worker-thread engine (ctx.workflows) over the spawn +# subagent backend above, plus the model-facing `workflow` tool. The model +# writes a JavaScript orchestration script (meta + body); the engine runs it +# in its own worker thread and fans agent() calls out as spawn children. - id: workflow-vm name: '@deepseek-ai/dsh-workflow-vm' config: diff --git a/packages/README.md b/packages/README.md index 3c38eda671..43b446eeb5 100644 --- a/packages/README.md +++ b/packages/README.md @@ -14,7 +14,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface | | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface | -| [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the node:vm engine, and the model-facing `workflow` tool | Product — stable surface | +| [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface | | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | diff --git a/packages/workflow/README.md b/packages/workflow/README.md index f28a325ea8..a0750d9fdf 100644 --- a/packages/workflow/README.md +++ b/packages/workflow/README.md @@ -5,9 +5,9 @@ The workflow seam: a model-written JavaScript orchestration script that fans out | Package | Role | ctx key | |---|---|---| | `workflow/` | Abstract workflow seam: service base class + run vocabulary + `workflow/*` events | `ctx.workflows` | -| `workflow-vm/` | In-process `node:vm` engine: parses the script, injects the hooks, drives `ctx.subagents` | (provides `ctx.workflows`) | +| `workflow-vm/` | `node:worker_threads` engine: one worker per run; the script's vm context lives inside the worker, `agent()` bridges to `ctx.subagents` over the message port | (provides `ctx.workflows`) | | `tool-workflow/` | Model-facing `workflow` tool over `ctx.workflows` | (registers on `ctx.tools`) | -The interface lives at `workflow/workflow/`. The engine's `agent()` hook rides the [subagent seam](../subagent/README.md) (any registered provider; the shipped examples use `spawn`), and `agent({ schema })` rides the structured-output support the in-process backends implement. The seam split exists for engine hardening: `node:vm` is in-process and cannot kill a pathological synchronous spin — a worker-thread or isolated-vm engine swaps in behind the same interface if that ever matters. +The interface lives at `workflow/workflow/`. The engine's `agent()` hook rides the [subagent seam](../subagent/README.md) (any registered provider; the shipped examples use `spawn`), and `agent({ schema })` rides the structured-output support the in-process backends implement. The worker thread isolates the SCRIPT — the host never blocks on it, and a cancelled run's post-grace termination is real — but it is NOT a security boundary; an isolated-vm/separate-process engine (actual sandboxing) swaps in behind the same interface if that ever matters. The proposal, decisions, and deferred work: [docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md](../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md). diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md index 076f5443ac..96add5017e 100644 --- a/packages/workflow/workflow/README.md +++ b/packages/workflow/workflow/README.md @@ -1,10 +1,10 @@ # @deepseek-ai/dsh-workflow -The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-vm`](../workflow-vm/README.md) is the first, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer. +The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-vm`](../workflow-vm/README.md) (one worker thread per run) is the implementation, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer. ## Service: `WorkflowService` (abstract) -`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` settles within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. +`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` settles within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. Runs are HOLDER-owned: the engine does not track its live runs, so disposing the engine's fiber mid-run leaves each run to its holder's teardown. The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits. @@ -22,7 +22,7 @@ All observe-only emits carrying DATA SNAPSHOTS (`WorkflowRunInfo` = id + meta) - `workflow/start`(info) / `workflow/end`(info, resultInfo) — run lifecycle; `resultInfo` deliberately omits the value. - `workflow/phase`(info, title) / `workflow/log`(info, message) — script narration. -- `workflow/agent-start`(info, agent) / `workflow/agent-end`(info, agent + outcome) — one pair per `agent()` call, correlated by `seq`. +- `workflow/agent-start`(info, agent) / `workflow/agent-end`(info, agent + outcome) — one pair per `agent()` call that STARTED a child run (a call rejected at validation or caps, refused at start, or cancelled while queued for a slot emits no pair), correlated by `seq`. ## Non-goals (this cut) diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 0e5a03c438..2a57d143b6 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -4,10 +4,10 @@ * that fans out subagents — without saying HOW. Implementations subclass * {@link WorkflowService} and register as the `workflows` service (one * implementation per context, cordis' standard duplicate-service behavior); - * `@deepseek-ai/dsh-workflow-vm` (an in-process `node:vm` engine) is the - * first. Future engines (a worker-thread or isolated-vm sandbox) swap in - * without touching the model-facing tool that consumes them - * (`@deepseek-ai/dsh-tool-workflow`). + * the implementation is `@deepseek-ai/dsh-workflow-vm`, which runs each + * script in its own worker thread. Hardened engines (an isolated-vm or + * separate-process sandbox) swap in without touching the model-facing tool + * that consumes them (`@deepseek-ai/dsh-tool-workflow`). * * The `workflow/*` lifecycle events are OBSERVE-ONLY data snapshots: they * carry {@link WorkflowRunInfo} (id + meta), never the live {@link WorkflowRun} @@ -198,6 +198,11 @@ export function isFatalWorkflowError(error: unknown): boolean { * for the script to settle AND its started children to finish disposing, * and abandons whatever is left rather than hanging its caller (the engine * documents what abandonment leaves behind). + * - Runs are HOLDER-OWNED: the engine hands control (`cancel`/`dispose`) to + * the `start()` caller and does not track its live runs — disposing the + * engine's own fiber mid-run deliberately leaves those runs to their + * holders' teardown, so an engine reload cannot yank a run out from under + * the consumer awaiting it. */ export abstract class WorkflowService extends Service { constructor(ctx: Context) { diff --git a/packages/workflow/workflow/src/types.ts b/packages/workflow/workflow/src/types.ts index 767fb8257b..8552e32454 100644 --- a/packages/workflow/workflow/src/types.ts +++ b/packages/workflow/workflow/src/types.ts @@ -89,7 +89,13 @@ export interface WorkflowResult { stopReason: WorkflowStopReason /** The failure message (present iff `stopReason` is not `completed`). */ error?: string - /** How many `agent()` calls the run accepted (whole lifetime, including calls still queued for a slot when the run was cancelled). */ + /** + * How many `agent()` calls the run accepted over its whole lifetime. On a + * graceful settlement this is the script-side count (calls still queued for + * a concurrency slot included); on a termination path (grace force-settle, + * worker death) it degrades to the host-observed count — calls queued + * inside a terminated script are unknowable then. + */ agentsStarted: number } @@ -98,18 +104,19 @@ export interface WorkflowResult { * `result`, may `cancel` mid-flight, and MUST `dispose` on every path. * `result` does NOT reject — a script failure resolves with `stopReason: * 'error'` — and once the run is cancelled it SETTLES within the engine's - * bounded grace even if the script itself never settles (the engine abandons - * the script and reports `cancelled`), so a consumer awaiting `result` is - * never wedged past a cancellation. `dispose()` = cancel + that bounded - * settle + child quiescence; it never hangs on a stuck script and is safe to - * call on every path (idempotent). + * bounded grace even if the script itself never settles (the engine + * force-settles `cancelled`; what becomes of the script is engine-documented + * — the worker-thread engine terminates its worker), so a consumer awaiting + * `result` is never wedged past a cancellation. `dispose()` = cancel + that + * bounded settle + child quiescence; it never hangs on a stuck script and is + * safe to call on every path (idempotent). */ export interface WorkflowRun { readonly id: WorkflowRunId /** The validated meta block (available before the body runs). */ readonly meta: WorkflowMeta readonly result: Promise - /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is abandoned at the grace). */ + /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is force-settled at the grace). */ cancel(reason?: string): void /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */ dispose(): Promise diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 1fabb98707..0abe1a34cf 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -193,7 +193,7 @@ const SERVICE_ROLES: ServiceRole[] = [ mode: 'seam', implementations: ['workflow-vm'], consumers: ['tool-workflow'], - note: 'One engine per context (bash shape, no named-provider registry); the vm engine fans agent() calls out through ctx.subagents.', + note: 'One engine per context (bash shape, no named-provider registry); the worker-thread engine fans agent() calls out through ctx.subagents.', }, ] @@ -203,6 +203,14 @@ const DYNAMIC_EVENT_DISPATCHERS: Array<{ event: string; pkg: string; method: str // listeners or strand an already-started child run. { event: 'subagent/start', pkg: 'subagent', method: 'events.dispatch' }, { event: 'subagent/end', pkg: 'subagent', method: 'events.dispatch' }, + // The workflow/* lifecycle events dispatch the same way, for the same + // per-listener-containment reason (WorkflowService.emitWorkflowEvent). + { event: 'workflow/start', pkg: 'workflow', method: 'events.dispatch' }, + { event: 'workflow/phase', pkg: 'workflow', method: 'events.dispatch' }, + { event: 'workflow/log', pkg: 'workflow', method: 'events.dispatch' }, + { event: 'workflow/agent-start', pkg: 'workflow', method: 'events.dispatch' }, + { event: 'workflow/agent-end', pkg: 'workflow', method: 'events.dispatch' }, + { event: 'workflow/end', pkg: 'workflow', method: 'events.dispatch' }, ] function generatedHeader(title: string): string[] { From 0d11a3afc708a7fcfd867bfc1022798b0a90e44a Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 19:06:55 +0800 Subject: [PATCH 099/119] workflow: rename dsh-workflow-vm to dsh-workflow-workerthread Pure mechanical rename now that the package's internals are the worker-thread engine: directory, package name, spec/e2e filenames, module tags and logger prefixes, tsconfig/knip/run-gates/AGENTS.md references, example cordis.yml plugin ids, doc links; catalogs regenerated and the lockfile refreshed. --- AGENTS.md | 4 ++-- docs/capability-seams.md | 6 +++--- docs/config-catalog.md | 4 ++-- docs/core-data-structures/workflow.md | 2 +- docs/module-graph.md | 16 ++++++++-------- .../feature/2026-07-05-dynamic-workflows.md | 2 +- examples/acp-agent/composition.md | 6 +++--- examples/acp-agent/cordis.yml | 4 ++-- examples/acp-agent/tests/acp.snapshot.ts | 2 +- examples/coding-agent/composition.md | 6 +++--- examples/coding-agent/cordis.yml | 4 ++-- knip.json | 2 +- packages/workflow/README.md | 2 +- packages/workflow/tool-workflow/package.json | 2 +- .../tool-workflow/tests/tool-workflow.spec.ts | 2 +- .../README.md | 2 +- .../package.json | 2 +- .../src/host.ts | 8 ++++---- .../src/index.ts | 2 +- .../src/meta.ts | 2 +- .../src/protocol.ts | 2 +- .../src/realm.ts | 2 +- .../src/runtime.ts | 2 +- .../src/session.ts | 2 +- .../src/types.ts | 2 +- .../src/worker.ts | 2 +- .../tests/built-worker.e2e.ts | 2 +- .../tests/integration.spec.ts | 2 +- .../tests/meta.spec.ts | 0 .../tests/realm.spec.ts | 0 .../tests/session.spec.ts | 0 .../tests/workflow-workerthread.e2e.ts} | 0 .../tests/workflow-workerthread.spec.ts} | 2 +- .../tsconfig.json | 0 .../tsdown.config.ts | 0 packages/workflow/workflow/README.md | 2 +- packages/workflow/workflow/src/index.ts | 2 +- pnpm-lock.yaml | 6 +++--- scripts/gen-doc-graphs.ts | 2 +- scripts/gen-tool-catalog.ts | 2 +- scripts/run-gates.ts | 2 +- tsconfig.build.json | 2 +- tsconfig.json | 2 +- 43 files changed, 59 insertions(+), 59 deletions(-) rename packages/workflow/{workflow-vm => workflow-workerthread}/README.md (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/package.json (97%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/host.ts (97%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/index.ts (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/meta.ts (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/protocol.ts (98%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/realm.ts (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/runtime.ts (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/session.ts (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/types.ts (98%) rename packages/workflow/{workflow-vm => workflow-workerthread}/src/worker.ts (93%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tests/built-worker.e2e.ts (97%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tests/integration.spec.ts (98%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tests/meta.spec.ts (100%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tests/realm.spec.ts (100%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tests/session.spec.ts (100%) rename packages/workflow/{workflow-vm/tests/workflow.e2e.ts => workflow-workerthread/tests/workflow-workerthread.e2e.ts} (100%) rename packages/workflow/{workflow-vm/tests/workflow-vm.spec.ts => workflow-workerthread/tests/workflow-workerthread.spec.ts} (99%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tsconfig.json (100%) rename packages/workflow/{workflow-vm => workflow-workerthread}/tsdown.config.ts (100%) diff --git a/AGENTS.md b/AGENTS.md index 5602b244ce..d0a7983b26 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai web/ web seam + search/fetch providers + model-facing web tools compact/ compaction seam + basic backend subagent/ subagent seam + spawn/fork/ACP backends + delegation tool - workflow/ workflow seam + worker-thread script engine + the workflow tool + workflow/ workflow seam + worker-thread engine + the workflow tool todo/ the todo_write tool hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends @@ -70,7 +70,7 @@ printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})' printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE' ls .sessions/_no-cwd/main-session-*.jsonl >/dev/null rm -rf .sessions -pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/workflow/workflow-vm/tests/built-worker.e2e.ts +pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts ``` `test:coverage`, not `test`, is the gating run ([why](docs/testing.md)); a sign-off counts only for commands actually run. diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 1a13bd2060..8f5f316916 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -62,7 +62,7 @@ flowchart LR pkg_web_fetch_local["web-fetch-local"] pkg_workflow["workflow"] svc_workflows["ctx.workflows
Workflow script engine"] - pkg_workflow_vm["workflow-vm"] + pkg_workflow_workerthread["workflow-workerthread"] pkg_tool_workflow["tool-workflow"] pkg_agent --> svc_agents pkg_agent_loop --> svc_agentLoop @@ -93,7 +93,7 @@ flowchart LR pkg_web_search_exa --> svc_web pkg_web_search_perplexity --> svc_web pkg_workflow --> svc_workflows - pkg_workflow_vm --> svc_workflows + pkg_workflow_workerthread --> svc_workflows svc_agentLoop --> pkg_agent_core svc_agents --> pkg_acp svc_agents --> pkg_agent_loop @@ -145,6 +145,6 @@ flowchart LR | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. | | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. | -| `ctx.workflows` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-vm`](../packages/workflow/workflow-vm) | [`tool-workflow`](../packages/workflow/tool-workflow) | - | One engine per context (bash shape, no named-provider registry); the worker-thread engine fans agent() calls out through ctx.subagents. | +| `ctx.workflows` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | [`tool-workflow`](../packages/workflow/tool-workflow) | - | One engine per context (bash shape, no named-provider registry); the worker-thread engine fans agent() calls out through ctx.subagents. | Maintenance mode: hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard. diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 300468dd70..1649ad4e26 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -800,7 +800,7 @@ export interface Config { Source: [`packages/web/web-search-perplexity/src/index.ts:33`](../packages/web/web-search-perplexity/src/index.ts) -## `@deepseek-ai/dsh-workflow-vm` +## `@deepseek-ai/dsh-workflow-workerthread` Requires: `subagents` @@ -826,7 +826,7 @@ export interface Config { } ``` -Source: [`packages/workflow/workflow-vm/src/index.ts:69`](../packages/workflow/workflow-vm/src/index.ts) +Source: [`packages/workflow/workflow-workerthread/src/index.ts:69`](../packages/workflow/workflow-workerthread/src/index.ts) ## Loadable plugins with no config diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md index 4d880ea948..36ad3be330 100644 --- a/docs/core-data-structures/workflow.md +++ b/docs/core-data-structures/workflow.md @@ -2,7 +2,7 @@ The workflow seam — an agent running a model-written orchestration SCRIPT that fans out subagents. Like [subagent](subagent.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). Unlike the subagent registry it takes the bash shape: ONE engine implementation per context provides `ctx.workflows`; there is no named-provider registry (a second engine is a plugin swap, not a co-resident). -Interface: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The implementation is [dsh-workflow-vm](../../packages/workflow/workflow-vm) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows RFC](../rfc/implemented/feature/2026-07-05-dynamic-workflows.md). +Interface: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The implementation is [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows RFC](../rfc/implemented/feature/2026-07-05-dynamic-workflows.md). Source: [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts) diff --git a/docs/module-graph.md b/docs/module-graph.md index ae1d8ef63f..f084e7fe40 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -81,7 +81,7 @@ flowchart TD subgraph group_workflow["packages/workflow"] pkg_tool_workflow["tool-workflow"] pkg_workflow["workflow"] - pkg_workflow_vm["workflow-vm"] + pkg_workflow_workerthread["workflow-workerthread"] end pkg_llm --> pkg_brand pkg_bash --> pkg_brand @@ -199,12 +199,12 @@ flowchart TD pkg_subagent_mock --> pkg_agent pkg_subagent_mock --> pkg_llm pkg_subagent_mock --> pkg_subagent - pkg_workflow_vm --> pkg_agent - pkg_workflow_vm --> pkg_brand - pkg_workflow_vm --> pkg_llm - pkg_workflow_vm --> pkg_subagent - pkg_workflow_vm --> pkg_tools - pkg_workflow_vm --> pkg_workflow + pkg_workflow_workerthread --> pkg_agent + pkg_workflow_workerthread --> pkg_brand + pkg_workflow_workerthread --> pkg_llm + pkg_workflow_workerthread --> pkg_subagent + pkg_workflow_workerthread --> pkg_tools + pkg_workflow_workerthread --> pkg_workflow pkg_subagent_fork --> pkg_agent pkg_subagent_fork --> pkg_session pkg_subagent_fork --> pkg_subagent @@ -268,7 +268,7 @@ flowchart TD | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | -| [`workflow-vm`](../packages/workflow/workflow-vm) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | +| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index d0e436b17e..029e090cb1 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -20,7 +20,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre `ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [core-data-structures/workflow.md](../../../core-data-structures/workflow.md). -### The engine (dsh-workflow-vm): one worker thread per run +### The engine (dsh-workflow-workerthread): one worker thread per run **Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) AND Node-API escape from the script's context — the vm context shares object machinery with its surrounding realm, so a script can reach the `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin; the absent globals are API surface, not containment, and a worker thread is NOT a security boundary (an escapee holds process-wide privileges — Node's permission model is per-process). Worker-side code MAY run script code while reading script values, and that is accepted: a synchronous spin costs the script its OWN thread (terminated at the post-cancel grace), never the host loop, so containing error VALUES would be cost without a threat model. Genuine sandboxing (isolated-vm, a separate process) remains an engine swap behind the seam, not incremental defenses here. diff --git a/examples/acp-agent/composition.md b/examples/acp-agent/composition.md index 57be4be05e..06290d326e 100644 --- a/examples/acp-agent/composition.md +++ b/examples/acp-agent/composition.md @@ -31,8 +31,8 @@ flowchart LR cfg --> plugin_acp_tool_subagent plugin_acp_tool_subagent_fork["tool-subagent-fork
@deepseek-ai/dsh-tool-subagent"] cfg --> plugin_acp_tool_subagent_fork - plugin_acp_workflow_vm["workflow-vm
@deepseek-ai/dsh-workflow-vm"] - cfg --> plugin_acp_workflow_vm + plugin_acp_workflow_workerthread["workflow-workerthread
@deepseek-ai/dsh-workflow-workerthread"] + cfg --> plugin_acp_workflow_workerthread plugin_acp_tool_workflow["tool-workflow
@deepseek-ai/dsh-tool-workflow"] cfg --> plugin_acp_tool_workflow plugin_acp_tool_todo["tool-todo
@deepseek-ai/dsh-tool-todo"] @@ -59,7 +59,7 @@ flowchart LR | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` | | `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` | | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` | -| `workflow-vm` | `@deepseek-ai/dsh-workflow-vm` | +| `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` | | `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` | | `tool-todo` | `@deepseek-ai/dsh-tool-todo` | | `fs-local` | `@deepseek-ai/dsh-fs-local` | diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml index f2015bc7c2..3a0d177005 100644 --- a/examples/acp-agent/cordis.yml +++ b/examples/acp-agent/cordis.yml @@ -86,8 +86,8 @@ # subagent backend above, plus the model-facing `workflow` tool. The model # writes a JavaScript orchestration script (meta + body); the engine runs it # in its own worker thread and fans agent() calls out as spawn children. -- id: workflow-vm - name: '@deepseek-ai/dsh-workflow-vm' +- id: workflow-workerthread + name: '@deepseek-ai/dsh-workflow-workerthread' config: provider: spawn diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 1c3e524903..944ccd9b5b 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -108,7 +108,7 @@ const SCENARIOS: Scenario[] = [ { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 }, { name: 'subagent-mixed', hasModelTurn: true, recorded: true, childSessions: 2 }, // The workflow tool: the model writes a one-child orchestration script; the - // child runs as a spawn subagent inside the vm engine (its session is the + // child runs as a spawn subagent under the worker-thread engine (its session is the // child fixture), and the tool result carries the script's return value. { name: 'workflow-run', hasModelTurn: true, recorded: true, childSessions: 1 }, // Hook matrix — one scenario per hook point × its headline Decision outcome, diff --git a/examples/coding-agent/composition.md b/examples/coding-agent/composition.md index 4ebf4c838d..be9a457124 100644 --- a/examples/coding-agent/composition.md +++ b/examples/coding-agent/composition.md @@ -35,8 +35,8 @@ flowchart LR cfg --> plugin_coding_tool_subagent plugin_coding_tool_subagent_fork["tool-subagent-fork
@deepseek-ai/dsh-tool-subagent"] cfg --> plugin_coding_tool_subagent_fork - plugin_coding_workflow_vm["workflow-vm
@deepseek-ai/dsh-workflow-vm"] - cfg --> plugin_coding_workflow_vm + plugin_coding_workflow_workerthread["workflow-workerthread
@deepseek-ai/dsh-workflow-workerthread"] + cfg --> plugin_coding_workflow_workerthread plugin_coding_tool_workflow["tool-workflow
@deepseek-ai/dsh-tool-workflow"] cfg --> plugin_coding_tool_workflow plugin_coding_tool_todo["tool-todo
@deepseek-ai/dsh-tool-todo"] @@ -61,7 +61,7 @@ flowchart LR | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` | | `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` | | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` | -| `workflow-vm` | `@deepseek-ai/dsh-workflow-vm` | +| `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` | | `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` | | `tool-todo` | `@deepseek-ai/dsh-tool-todo` | | `fs-local` | `@deepseek-ai/dsh-fs-local` | diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml index ee55bced0b..cf2e267e06 100644 --- a/examples/coding-agent/cordis.yml +++ b/examples/coding-agent/cordis.yml @@ -107,8 +107,8 @@ # subagent backend above, plus the model-facing `workflow` tool. The model # writes a JavaScript orchestration script (meta + body); the engine runs it # in its own worker thread and fans agent() calls out as spawn children. -- id: workflow-vm - name: '@deepseek-ai/dsh-workflow-vm' +- id: workflow-workerthread + name: '@deepseek-ai/dsh-workflow-workerthread' config: provider: spawn diff --git a/knip.json b/knip.json index 717148a10a..5342aadc29 100644 --- a/knip.json +++ b/knip.json @@ -41,7 +41,7 @@ "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, - "packages/workflow/workflow-vm": { + "packages/workflow/workflow-workerthread": { "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"] }, diff --git a/packages/workflow/README.md b/packages/workflow/README.md index a0750d9fdf..98fa3cfe04 100644 --- a/packages/workflow/README.md +++ b/packages/workflow/README.md @@ -5,7 +5,7 @@ The workflow seam: a model-written JavaScript orchestration script that fans out | Package | Role | ctx key | |---|---|---| | `workflow/` | Abstract workflow seam: service base class + run vocabulary + `workflow/*` events | `ctx.workflows` | -| `workflow-vm/` | `node:worker_threads` engine: one worker per run; the script's vm context lives inside the worker, `agent()` bridges to `ctx.subagents` over the message port | (provides `ctx.workflows`) | +| `workflow-workerthread/` | `node:worker_threads` engine: one worker per run; the script's vm context lives inside the worker, `agent()` bridges to `ctx.subagents` over the message port | (provides `ctx.workflows`) | | `tool-workflow/` | Model-facing `workflow` tool over `ctx.workflows` | (registers on `ctx.tools`) | The interface lives at `workflow/workflow/`. The engine's `agent()` hook rides the [subagent seam](../subagent/README.md) (any registered provider; the shipped examples use `spawn`), and `agent({ schema })` rides the structured-output support the in-process backends implement. The worker thread isolates the SCRIPT — the host never blocks on it, and a cancelled run's post-grace termination is real — but it is NOT a security boundary; an isolated-vm/separate-process engine (actual sandboxing) swaps in behind the same interface if that ever matters. diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json index 7fb0d1ec48..f5c2138d85 100644 --- a/packages/workflow/tool-workflow/package.json +++ b/packages/workflow/tool-workflow/package.json @@ -40,7 +40,7 @@ "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-workflow": "workspace:^", - "@deepseek-ai/dsh-workflow-vm": "workspace:^", + "@deepseek-ai/dsh-workflow-workerthread": "workspace:^", "cordis": "^4.0.0-rc.6" } } diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts index 2b6503cd45..dafc39bf46 100644 --- a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts +++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts @@ -10,7 +10,7 @@ import { WorkflowRunId, WorkflowService } from '@deepseek-ai/dsh-workflow' import type { WorkflowResult, WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' import { CallId } from '@deepseek-ai/dsh-llm' import SubagentService from '@deepseek-ai/dsh-subagent' -import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' +import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread' import * as toolWorkflow from '../src/index.ts' /** A controllable engine standing in behind ctx.workflows (the tool's only seam). */ diff --git a/packages/workflow/workflow-vm/README.md b/packages/workflow/workflow-workerthread/README.md similarity index 99% rename from packages/workflow/workflow-vm/README.md rename to packages/workflow/workflow-workerthread/README.md index 9a0ab21fef..0e763bdee9 100644 --- a/packages/workflow/workflow-vm/README.md +++ b/packages/workflow/workflow-workerthread/README.md @@ -1,4 +1,4 @@ -# @deepseek-ai/dsh-workflow-vm +# @deepseek-ai/dsh-workflow-workerthread The [`WorkflowService`](../workflow/README.md) implementation, on **`node:worker_threads`**: each run gets its OWN worker thread (one run = one worker, no pooling — a run is heavyweight, so the ~tens-of-ms thread spin-up is noise), the script executes in a vm context INSIDE that worker with the workflow hooks injected, and every `agent()` call bridges back over the message port to [`ctx.subagents`](../../subagent/README.md) on the host. Child agents are I/O-bound LLM loops and stay on the host event loop; the thread isolates the SCRIPT, the only part that can spin synchronously. diff --git a/packages/workflow/workflow-vm/package.json b/packages/workflow/workflow-workerthread/package.json similarity index 97% rename from packages/workflow/workflow-vm/package.json rename to packages/workflow/workflow-workerthread/package.json index a174893b9c..f86c74c2f7 100644 --- a/packages/workflow/workflow-vm/package.json +++ b/packages/workflow/workflow-workerthread/package.json @@ -1,5 +1,5 @@ { - "name": "@deepseek-ai/dsh-workflow-vm", + "name": "@deepseek-ai/dsh-workflow-workerthread", "description": "worker-thread workflow engine: executes model-written orchestration scripts off the host event loop, bridging agent() calls back to ctx.subagents", "version": "0.0.1", "private": true, diff --git a/packages/workflow/workflow-vm/src/host.ts b/packages/workflow/workflow-workerthread/src/host.ts similarity index 97% rename from packages/workflow/workflow-vm/src/host.ts rename to packages/workflow/workflow-workerthread/src/host.ts index b329e0c7d2..9d98d00933 100644 --- a/packages/workflow/workflow-vm/src/host.ts +++ b/packages/workflow/workflow-workerthread/src/host.ts @@ -22,7 +22,7 @@ * still queued worker-side for a concurrency slot are unknowable then; the * worker's own count rides the result message on every graceful path. * - * @module @deepseek-ai/dsh-workflow-vm/host + * @module @deepseek-ai/dsh-workflow-workerthread/host */ import { fileURLToPath } from 'node:url' @@ -190,7 +190,7 @@ export class WorkerRun implements WorkflowRun { // data, so serialization cannot fail); there is nothing left to // deliver to — log and move on. /* v8 ignore next -- postMessage teardown race (a throw between exit and its event): not constructible in-process */ - this.ctx.logger.warn(`workflow-vm: postMessage failed: ${renderThrown(error)}`) + this.ctx.logger.warn(`workflow-workerthread: postMessage failed: ${renderThrown(error)}`) } } @@ -293,7 +293,7 @@ export class WorkerRun implements WorkflowRun { // The subagent seam's dispose() is not supposed to reject; a backend // that does anyway must not wedge the script's finally (which awaits // the ack) — ack and move on. - this.ctx.logger.warn(`workflow-vm: child dispose failed: ${renderThrown(error)}`) + this.ctx.logger.warn(`workflow-workerthread: child dispose failed: ${renderThrown(error)}`) this.finishChild(callId) this.post(HostToWorkerType.ChildDisposed, { callId }) }, @@ -322,7 +322,7 @@ export class WorkerRun implements WorkflowRun { void run.dispose().then( () => { this.finishChild(callId) }, (error: unknown) => { - this.ctx.logger.warn(`workflow-vm: child dispose failed during reap: ${renderThrown(error)}`) + this.ctx.logger.warn(`workflow-workerthread: child dispose failed during reap: ${renderThrown(error)}`) this.finishChild(callId) }, ) diff --git a/packages/workflow/workflow-vm/src/index.ts b/packages/workflow/workflow-workerthread/src/index.ts similarity index 99% rename from packages/workflow/workflow-vm/src/index.ts rename to packages/workflow/workflow-workerthread/src/index.ts index 1b65381bfb..538252d90a 100644 --- a/packages/workflow/workflow-vm/src/index.ts +++ b/packages/workflow/workflow-workerthread/src/index.ts @@ -36,7 +36,7 @@ * Plugin export shape: a default-exported {@link WorkflowService} subclass * (the class-based service form, like `dsh-bash-local`). * - * @module @deepseek-ai/dsh-workflow-vm + * @module @deepseek-ai/dsh-workflow-workerthread */ import { randomUUID } from 'node:crypto' diff --git a/packages/workflow/workflow-vm/src/meta.ts b/packages/workflow/workflow-workerthread/src/meta.ts similarity index 99% rename from packages/workflow/workflow-vm/src/meta.ts rename to packages/workflow/workflow-workerthread/src/meta.ts index 75958ba6f1..e818bc6f00 100644 --- a/packages/workflow/workflow-vm/src/meta.ts +++ b/packages/workflow/workflow-workerthread/src/meta.ts @@ -14,7 +14,7 @@ * result — not the source — is the contract: it must materialize to plain * JSON data and pass the shape validation). * - * @module @deepseek-ai/dsh-workflow-vm/meta + * @module @deepseek-ai/dsh-workflow-workerthread/meta */ import * as vm from 'node:vm' diff --git a/packages/workflow/workflow-vm/src/protocol.ts b/packages/workflow/workflow-workerthread/src/protocol.ts similarity index 98% rename from packages/workflow/workflow-vm/src/protocol.ts rename to packages/workflow/workflow-workerthread/src/protocol.ts index 293676706e..ed6b54950a 100644 --- a/packages/workflow/workflow-vm/src/protocol.ts +++ b/packages/workflow/workflow-workerthread/src/protocol.ts @@ -13,7 +13,7 @@ * `post(type, payload)` whose payload parameter is looked up from the map, * so a tag/payload mismatch is a compile error at the call site. * - * @module @deepseek-ai/dsh-workflow-vm/protocol + * @module @deepseek-ai/dsh-workflow-workerthread/protocol */ import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowResult } from '@deepseek-ai/dsh-workflow' diff --git a/packages/workflow/workflow-vm/src/realm.ts b/packages/workflow/workflow-workerthread/src/realm.ts similarity index 99% rename from packages/workflow/workflow-vm/src/realm.ts rename to packages/workflow/workflow-workerthread/src/realm.ts index 017de76069..393716c279 100644 --- a/packages/workflow/workflow-vm/src/realm.ts +++ b/packages/workflow/workflow-workerthread/src/realm.ts @@ -27,7 +27,7 @@ * thrown by a hook is built OUTSIDE the script's vm context, so an in-script * `instanceof Error` check is false; read `name`/`code`/`message` instead. * - * @module @deepseek-ai/dsh-workflow-vm/realm + * @module @deepseek-ai/dsh-workflow-workerthread/realm */ /** Thrown by {@link materializeFromRealm}; the caller wraps it into the right `WorkflowError` code. */ diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-workerthread/src/runtime.ts similarity index 99% rename from packages/workflow/workflow-vm/src/runtime.ts rename to packages/workflow/workflow-workerthread/src/runtime.ts index 3005520fa0..28450977c3 100644 --- a/packages/workflow/workflow-vm/src/runtime.ts +++ b/packages/workflow/workflow-workerthread/src/runtime.ts @@ -33,7 +33,7 @@ * the settles-within-grace guarantee by force-settling `cancelled` and * terminating the worker — the real kill an in-process engine could not have. * - * @module @deepseek-ai/dsh-workflow-vm/runtime + * @module @deepseek-ai/dsh-workflow-workerthread/runtime */ import * as vm from 'node:vm' diff --git a/packages/workflow/workflow-vm/src/session.ts b/packages/workflow/workflow-workerthread/src/session.ts similarity index 99% rename from packages/workflow/workflow-vm/src/session.ts rename to packages/workflow/workflow-workerthread/src/session.ts index 131f760ff9..718b8ac54d 100644 --- a/packages/workflow/workflow-vm/src/session.ts +++ b/packages/workflow/workflow-workerthread/src/session.ts @@ -14,7 +14,7 @@ * A `cancel` arriving instead of `go` still releases the gate: `drive()` * sees the cancelled state and settles without running the body. * - * @module @deepseek-ai/dsh-workflow-vm/session + * @module @deepseek-ai/dsh-workflow-workerthread/session */ import type { MessagePort } from 'node:worker_threads' diff --git a/packages/workflow/workflow-vm/src/types.ts b/packages/workflow/workflow-workerthread/src/types.ts similarity index 98% rename from packages/workflow/workflow-vm/src/types.ts rename to packages/workflow/workflow-workerthread/src/types.ts index c87fc4668c..329523ffc8 100644 --- a/packages/workflow/workflow-vm/src/types.ts +++ b/packages/workflow/workflow-workerthread/src/types.ts @@ -6,7 +6,7 @@ * JSON data by construction, so the structured-clone hop never meets a value * it cannot carry. Types only, per the package convention. * - * @module @deepseek-ai/dsh-workflow-vm/types + * @module @deepseek-ai/dsh-workflow-workerthread/types */ import type { ContentBlock } from '@deepseek-ai/dsh-llm' diff --git a/packages/workflow/workflow-vm/src/worker.ts b/packages/workflow/workflow-workerthread/src/worker.ts similarity index 93% rename from packages/workflow/workflow-vm/src/worker.ts rename to packages/workflow/workflow-workerthread/src/worker.ts index 3b20600d7d..f468ad9a53 100644 --- a/packages/workflow/workflow-vm/src/worker.ts +++ b/packages/workflow/workflow-workerthread/src/worker.ts @@ -6,7 +6,7 @@ * coverage); loading this module on the main thread throws via * `requireParentPort`, which is how the suite covers the file itself. * - * @module @deepseek-ai/dsh-workflow-vm/worker + * @module @deepseek-ai/dsh-workflow-workerthread/worker */ import { parentPort, workerData } from 'node:worker_threads' diff --git a/packages/workflow/workflow-vm/tests/built-worker.e2e.ts b/packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts similarity index 97% rename from packages/workflow/workflow-vm/tests/built-worker.e2e.ts rename to packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts index 9bdd3865bb..d541b4c0ff 100644 --- a/packages/workflow/workflow-vm/tests/built-worker.e2e.ts +++ b/packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts @@ -28,7 +28,7 @@ describe.skipIf(!existsSync(builtIndex) || !existsSync(builtWorker))('built work await writeFile(driver, ` import { Context } from 'cordis' import SubagentService from '@deepseek-ai/dsh-subagent' -import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' +import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread' const ctx = new Context() await ctx.plugin(SubagentService) diff --git a/packages/workflow/workflow-vm/tests/integration.spec.ts b/packages/workflow/workflow-workerthread/tests/integration.spec.ts similarity index 98% rename from packages/workflow/workflow-vm/tests/integration.spec.ts rename to packages/workflow/workflow-workerthread/tests/integration.spec.ts index e53ea518bc..ae58a536f8 100644 --- a/packages/workflow/workflow-vm/tests/integration.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/integration.spec.ts @@ -41,7 +41,7 @@ async function setup(script: Script) { return { ctx, parent, adapter } } -describe('dsh-workflow-vm over the real in-process stack', () => { +describe('dsh-workflow-workerthread over the real in-process stack', () => { it('runs a two-stage workflow: a plain child, then a schema child through the structured runtime', async () => { const { ctx, parent } = await setup([ textResponse('the file list is a.ts'), diff --git a/packages/workflow/workflow-vm/tests/meta.spec.ts b/packages/workflow/workflow-workerthread/tests/meta.spec.ts similarity index 100% rename from packages/workflow/workflow-vm/tests/meta.spec.ts rename to packages/workflow/workflow-workerthread/tests/meta.spec.ts diff --git a/packages/workflow/workflow-vm/tests/realm.spec.ts b/packages/workflow/workflow-workerthread/tests/realm.spec.ts similarity index 100% rename from packages/workflow/workflow-vm/tests/realm.spec.ts rename to packages/workflow/workflow-workerthread/tests/realm.spec.ts diff --git a/packages/workflow/workflow-vm/tests/session.spec.ts b/packages/workflow/workflow-workerthread/tests/session.spec.ts similarity index 100% rename from packages/workflow/workflow-vm/tests/session.spec.ts rename to packages/workflow/workflow-workerthread/tests/session.spec.ts diff --git a/packages/workflow/workflow-vm/tests/workflow.e2e.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts similarity index 100% rename from packages/workflow/workflow-vm/tests/workflow.e2e.ts rename to packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts diff --git a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts similarity index 99% rename from packages/workflow/workflow-vm/tests/workflow-vm.spec.ts rename to packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index 7264877f48..9e2218c167 100644 --- a/packages/workflow/workflow-vm/tests/workflow-vm.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -119,7 +119,7 @@ async function run(ctx: Context, parent: Agent, source: string, args?: unknown): } } -describe('dsh-workflow-vm', () => { +describe('dsh-workflow-workerthread', () => { describe('script execution over a real worker thread', () => { it('runs a script end-to-end: agent() text results, phases, log, args, return value, events', async () => { const { ctx, parent, provider } = await setup({ reply: (_request, index) => text(`answer-${index}`) }) diff --git a/packages/workflow/workflow-vm/tsconfig.json b/packages/workflow/workflow-workerthread/tsconfig.json similarity index 100% rename from packages/workflow/workflow-vm/tsconfig.json rename to packages/workflow/workflow-workerthread/tsconfig.json diff --git a/packages/workflow/workflow-vm/tsdown.config.ts b/packages/workflow/workflow-workerthread/tsdown.config.ts similarity index 100% rename from packages/workflow/workflow-vm/tsdown.config.ts rename to packages/workflow/workflow-workerthread/tsdown.config.ts diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md index 96add5017e..317aaf9f81 100644 --- a/packages/workflow/workflow/README.md +++ b/packages/workflow/workflow/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-workflow -The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-vm`](../workflow-vm/README.md) (one worker thread per run) is the implementation, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer. +The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-workerthread`](../workflow-workerthread/README.md) (one worker thread per run) is the implementation, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer. ## Service: `WorkflowService` (abstract) diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 2a57d143b6..6c2b797362 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -4,7 +4,7 @@ * that fans out subagents — without saying HOW. Implementations subclass * {@link WorkflowService} and register as the `workflows` service (one * implementation per context, cordis' standard duplicate-service behavior); - * the implementation is `@deepseek-ai/dsh-workflow-vm`, which runs each + * the implementation is `@deepseek-ai/dsh-workflow-workerthread`, which runs each * script in its own worker thread. Hardened engines (an isolated-vm or * separate-process sandbox) swap in without touching the model-facing tool * that consumes them (`@deepseek-ai/dsh-tool-workflow`). diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e3e1892e35..c3ce677f83 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1092,9 +1092,9 @@ importers: '@deepseek-ai/dsh-workflow': specifier: workspace:^ version: link:../workflow - '@deepseek-ai/dsh-workflow-vm': + '@deepseek-ai/dsh-workflow-workerthread': specifier: workspace:^ - version: link:../workflow-vm + version: link:../workflow-workerthread cordis: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) @@ -1117,7 +1117,7 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) - packages/workflow/workflow-vm: + packages/workflow/workflow-workerthread: dependencies: schemastery: specifier: ^3.18.0 diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 0abe1a34cf..31e010f55c 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -191,7 +191,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'workflow', title: 'Workflow script engine', mode: 'seam', - implementations: ['workflow-vm'], + implementations: ['workflow-workerthread'], consumers: ['tool-workflow'], note: 'One engine per context (bash shape, no named-provider registry); the worker-thread engine fans agent() calls out through ctx.subagents.', }, diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 27481a6304..42795ec00e 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -51,7 +51,7 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs' import * as ToolTodo from '@deepseek-ai/dsh-tool-todo' import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent' import * as ToolWeb from '@deepseek-ai/dsh-tool-web' -import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-vm' +import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread' import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow' const root = resolve(import.meta.dirname, '..') diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 25e08cf8d2..3b4a3568cb 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -313,7 +313,7 @@ function builtBinSmokeGate(): Gate { // The workflow engine's built worker bundle: the only automated proof // that lib/index.js resolves its sibling lib/worker.js under plain node // (the e2e lane runs unbuilt, so this file self-skips there). - 'packages/workflow/workflow-vm/tests/built-worker.e2e.ts', + 'packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts', ], { label: 'built-bin smoke', needs: ['build'], diff --git a/tsconfig.build.json b/tsconfig.build.json index 93cce8f4b9..018c29ec37 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -52,7 +52,7 @@ { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/workflow/workflow" }, - { "path": "./packages/workflow/workflow-vm" }, + { "path": "./packages/workflow/workflow-workerthread" }, { "path": "./packages/workflow/tool-workflow" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/hooks/hook-protocol" }, diff --git a/tsconfig.json b/tsconfig.json index ba5ccbac26..0cad85791c 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -63,7 +63,7 @@ { "path": "./packages/subagent/subagent-fork" }, { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/workflow/workflow" }, - { "path": "./packages/workflow/workflow-vm" }, + { "path": "./packages/workflow/workflow-workerthread" }, { "path": "./packages/workflow/tool-workflow" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/hooks/hook-protocol" }, From af9616f47d87f317d5bc07b90015b3bdaee7524c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 19:12:58 +0800 Subject: [PATCH 100/119] test: let the wedged-worker regression post its child-start first MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The regression's script spun immediately after calling agent(), but the agent() continuation (which posts the child-start RPC) only runs on a microtask tick — the spin seized the worker's loop before the post, so the host never saw a child inside the waitFor window. A few await-null yields before the spin let the RPC out; the posted message needs no further worker-loop turns to reach the host, so the wedge still holds for the Cancel message the test is about. --- .../tests/workflow-workerthread.spec.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index 9e2218c167..20911d052e 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -511,9 +511,13 @@ describe('dsh-workflow-workerthread', () => { // The stray child's start RPC reaches the host, then the script wedges // its own worker in a synchronous spin: the worker cannot process the // Cancel message, so it can relay NO ChildCancel RPC — only the host's - // own children loop can deliver the explicit cancel in time. + // own children loop can deliver the explicit cancel in time. The + // microtask yields let the agent() continuation POST its child-start + // before the spin seizes the worker's loop (the posted message needs + // no further worker-loop turns to reach the host). script: script(` agent('wedged child') + for (let i = 0; i < 20; i++) await null const end = Date.now() + 1500 while (Date.now() < end) {} return 'raced' From 0d0f0204f206fbea27530919f49c48cf0f3245d6 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 20:09:10 +0800 Subject: [PATCH 101/119] =?UTF-8?q?workflow:=20meta=20rides=20the=20seam?= =?UTF-8?q?=20as=20data=20=E2=80=94=20the=20engine=20never=20evaluates=20i?= =?UTF-8?q?t?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 review finding: extractMeta timed only the literal's vm evaluation; materializing the RESULT then read properties ordinarily on the HOST stack, so a meta literal smuggling a getter (get name() { while(true){} }) could wedge the host outside any timeout — defeating the exact spin isolation the worker thread exists for. Rather than harden the evaluator (descriptor walks, AST validation), delete the mechanism: the workflow's identity now reaches the seam as a plain JSON field (WorkflowStartRequest.meta), carried by the tool as a schema-validated `meta` object parameter the model fills directly. The engine only shape-validates data (validateMeta, every violation named) and pre-parses the body; the scanner, the vm evaluation, and the host-side materialization are gone, and with them the hole. A body still opening with a Claude Code-style `export const meta` statement gets a pointed SCRIPT_PARSE message (the likeliest authoring slip; a CC script's body stays drop-in, only its meta header moves into the parameter). syncTimeoutMs now governs exactly one thing: the initial synchronous slice inside the worker. The RFC's decision section is rewritten in place (implemented-RFC rule); the embedded-meta format moves to alternatives-considered with the hole as the reason. Tool description, presentation (title now reads meta.name directly — the textual sniff is gone), seam vocabulary docs, and catalogs follow. --- docs/config-catalog.md | 4 +- docs/core-data-structures/workflow.md | 7 +- .../feature/2026-07-05-dynamic-workflows.md | 10 +- docs/tool-catalog.md | 53 +++- packages/workflow/tool-workflow/src/index.ts | 53 ++-- .../tool-workflow/tests/tool-workflow.spec.ts | 46 ++-- .../workflow/workflow-workerthread/README.md | 8 +- .../workflow-workerthread/src/index.ts | 35 ++- .../workflow-workerthread/src/meta.ts | 196 ++------------- .../workflow-workerthread/src/runtime.ts | 2 +- .../workflow-workerthread/src/types.ts | 4 +- .../tests/built-worker.e2e.ts | 3 +- .../tests/integration.spec.ts | 8 +- .../workflow-workerthread/tests/meta.spec.ts | 228 +++++------------- .../tests/workflow-workerthread.e2e.ts | 6 +- .../tests/workflow-workerthread.spec.ts | 79 +++--- packages/workflow/workflow/README.md | 2 +- packages/workflow/workflow/src/types.ts | 22 +- 18 files changed, 304 insertions(+), 462 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 1649ad4e26..65ef893528 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -685,7 +685,7 @@ export interface Config { } ``` -Source: [`packages/workflow/tool-workflow/src/index.ts:40`](../packages/workflow/tool-workflow/src/index.ts) +Source: [`packages/workflow/tool-workflow/src/index.ts:39`](../packages/workflow/tool-workflow/src/index.ts) ## `@deepseek-ai/dsh-web` @@ -815,7 +815,7 @@ export interface Config { maxTotalAgents?: number /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */ maxItemsPerCall?: number - /** vm timeout for the initial synchronous slice (inside the worker) AND the host-side meta evaluation (default 5000 ms). */ + /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */ syncTimeoutMs?: number /** * How long after a cancellation an unsettled script may keep running before diff --git a/docs/core-data-structures/workflow.md b/docs/core-data-structures/workflow.md index 36ad3be330..4354105e70 100644 --- a/docs/core-data-structures/workflow.md +++ b/docs/core-data-structures/workflow.md @@ -8,20 +8,21 @@ Source: [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/work ## The start request -What a caller asks for when starting a run. The tool layer builds this from the model's `{ script, args }` plus the calling agent; the engine validates the script's meta block BEFORE the body runs. `parent` is REQUIRED — every child the script spawns is attributed to it (cwd, lineage, and depth flow through the [subagent seam](subagent.md)). `args` must be plain host-realm JSON data; the engine exposes it to the script as the `args` global. +What a caller asks for when starting a run. The tool layer builds this from the model's `{ script, meta, args }` call plus the calling agent; `meta` and `args` are plain JSON DATA (the engine shape-validates `meta` and rejects loud BEFORE anything runs — no script text is ever evaluated to obtain it). `parent` is REQUIRED — every child the script spawns is attributed to it (cwd, lineage, and depth flow through the [subagent seam](subagent.md)). ```ts type-equiv interface WorkflowStartRequest { script: string + meta: WorkflowMeta args?: unknown parent: Agent signal?: AbortSignal } ``` -## The script's identity: `WorkflowMeta` +## The workflow's identity: `WorkflowMeta` -The validated `export const meta` block (Claude Code dynamic-workflows format — a PURE object literal heading the script). `phases` is progress vocabulary only: `phase()` calls match titles for observers; no execution structure is implied. +The identity block carried as data on the start request (the tool's `meta` parameter; the field vocabulary matches the Claude Code dynamic-workflows meta block). `phases` is progress vocabulary only: `phase()` calls match titles for observers; no execution structure is implied. ```ts type-equiv interface WorkflowMeta { diff --git a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md index 029e090cb1..2f711651f6 100644 --- a/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md @@ -12,7 +12,7 @@ A workflow capability family at `packages/workflow/` in the bash seam shape (int ### The script contract (Claude Code-compatible) -A script is `export const meta = {...}` (a PURE object literal: `name`, `description`, optional `whenToUse`/`phases`) followed by a plain-JS body with top-level `await`, ending in `return `. The body sees exactly: `agent(prompt, {label, phase, schema, model})`, `parallel(thunks)`, `pipeline(items, ...stages)` (NO cross-stage barrier; `(prev, item, index)` callbacks), `phase(title)`, `log(message)`, and `args`. CC semantics are preserved where they matter to script authors: a failed child resolves `null` (scripts `.filter(Boolean)`); an ordinary stage throw nulls the ITEM and skips its remaining stages. CC's determinism bans (`Date.now()`/`Math.random()`/argless `new Date()` throwing) are NOT enforced — they exist for CC's journaling/resume, which this cut defers — so a CC-authored script runs unchanged while scripts written here may freely read the clock. +A workflow call is two parts: a `meta` JSON parameter (the identity block — `name`, `description`, optional `whenToUse`/`phases`; the field vocabulary matches Claude Code's meta block) and a `script` — a plain-JS body with top-level `await`, ending in `return `. Meta is DATA, never code: the engine shape-validates it and evaluates no script text to obtain it (a body still opening with a CC-style `export const meta` statement is rejected with a pointed message). The body sees exactly: `agent(prompt, {label, phase, schema, model})`, `parallel(thunks)`, `pipeline(items, ...stages)` (NO cross-stage barrier; `(prev, item, index)` callbacks), `phase(title)`, `log(message)`, and `args`. CC semantics are preserved where they matter to script authors: a failed child resolves `null` (scripts `.filter(Boolean)`); an ordinary stage throw nulls the ITEM and skips its remaining stages. CC's determinism bans (`Date.now()`/`Math.random()`/argless `new Date()` throwing) are NOT enforced — they exist for CC's journaling/resume, which this cut defers — so a CC-authored BODY runs unchanged (its meta header moves into the parameter) while scripts written here may freely read the clock. One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferred options (`effort`/`isolation`/`agentType`), malformed arguments, schemas outside the supported subset, tripped caps, seam start failures — throws a `WorkflowError` with `fatal: true`, and the combinators RE-THROW fatal errors instead of nulling the item. Without this, a typo'd option dissolves into a `null` indistinguishable from a child failure — the accepted-then-ignored failure mode this repo bans. One addition: the tool's `args` parameter is a JSON OBJECT (a bare list is wrapped as a field) so the wire schema stays honest. @@ -24,15 +24,15 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre **Trust premise (governs every engine decision below)**: workflow scripts are MODEL-WRITTEN — the same trust level as the model's existing bash access — so the engine defends against BUGGY scripts, never hostile ones. In scope: `result` never rejects, no unhandled rejections from dropped hook promises, loud rejection of values JSON cannot carry, fatal-vs-null hook discipline, cancellation that always frees the caller. Out of scope, deliberately: adversarial values (throwing/spinning accessors, proxies with hostile traps, prototype forgery, `prepareStackTrace` hijack) AND Node-API escape from the script's context — the vm context shares object machinery with its surrounding realm, so a script can reach the `Function` constructor (`globalThis.constructor.constructor`) and from it `process` and every Node builtin; the absent globals are API surface, not containment, and a worker thread is NOT a security boundary (an escapee holds process-wide privileges — Node's permission model is per-process). Worker-side code MAY run script code while reading script values, and that is accepted: a synchronous spin costs the script its OWN thread (terminated at the post-cancel grace), never the host loop, so containing error VALUES would be cost without a threat model. Genuine sandboxing (isolated-vm, a separate process) remains an engine swap behind the seam, not incremental defenses here. -**Why node:worker_threads**: one run = one worker thread, no pooling — a run is heavyweight (many children), so thread spin-up (~tens of ms) is noise. The script runs in a vm context INSIDE the worker, keeping the script-visible surface exactly the hook contract above (a bare worker realm would leak `setTimeout`/`fetch`/`process` as accidental API), and every `agent()` bridges to `ctx.subagents` by message-port RPC — children are I/O-bound LLM loops and stay on the host loop; the thread isolates the SCRIPT, the only part that can spin. What the thread buys: `start()` never blocks the host (an in-process engine runs the initial synchronous slice inline and cannot kill a spin past the first await — it could only ABANDON such a script, leaving the spin on the host loop), the post-cancel grace ends in a REAL `worker.terminate()`, and the value boundary is serialization by construction. isolated-vm was rejected for actual sandboxing: maintenance mode, `--no-node-snapshot` on EVERY consumer process (including published bins) on Node ≥ 20, node-gyp source-build fallback. Key mechanics (details in the package README): meta extraction and a body pre-parse stay HOST-side (preserving the seam's synchronous throws), a ready→go handshake keeps a run cancelled before start from ever executing the body, `cancel()` drives both child-cancel channels host-side (the shared request signal AND each child's explicit `cancel()` — a wedged worker cannot relay its own cancel RPCs), a host-side child registry backs worker-death reaping and `dispose()` quiescence, the wire protocol is enum-keyed payload maps private to the package, and on a termination path `agentsStarted` degrades to the host-observed count. Coverage puts the worker-side session on an in-process `MessageChannel` (real-Worker code is invisible to main-process v8) and proves the built `lib/worker.js` — a second tsdown entry, sanctioned in the workspace-constraints gate by the `"./worker"` subpath export — under plain node in the built-bin smoke gate. +**Why node:worker_threads**: one run = one worker thread, no pooling — a run is heavyweight (many children), so thread spin-up (~tens of ms) is noise. The script runs in a vm context INSIDE the worker, keeping the script-visible surface exactly the hook contract above (a bare worker realm would leak `setTimeout`/`fetch`/`process` as accidental API), and every `agent()` bridges to `ctx.subagents` by message-port RPC — children are I/O-bound LLM loops and stay on the host loop; the thread isolates the SCRIPT, the only part that can spin. What the thread buys: `start()` never blocks the host (an in-process engine runs the initial synchronous slice inline and cannot kill a spin past the first await — it could only ABANDON such a script, leaving the spin on the host loop), the post-cancel grace ends in a REAL `worker.terminate()`, and the value boundary is serialization by construction. isolated-vm was rejected for actual sandboxing: maintenance mode, `--no-node-snapshot` on EVERY consumer process (including published bins) on Node ≥ 20, node-gyp source-build fallback. Key mechanics (details in the package README): meta shape-validation and a body pre-parse stay HOST-side (preserving the seam's synchronous throws), a ready→go handshake keeps a run cancelled before start from ever executing the body, `cancel()` drives both child-cancel channels host-side (the shared request signal AND each child's explicit `cancel()` — a wedged worker cannot relay its own cancel RPCs), a host-side child registry backs worker-death reaping and `dispose()` quiescence, the wire protocol is enum-keyed payload maps private to the package, and on a termination path `agentsStarted` degrades to the host-observed count. Coverage puts the worker-side session on an in-process `MessageChannel` (real-Worker code is invisible to main-process v8) and proves the built `lib/worker.js` — a second tsdown entry, sanctioned in the workspace-constraints gate by the `"./worker"` subpath export — under plain node in the built-bin smoke gate. -**Meta extraction**: a string/comment-aware brace scanner (template interpolation rejected) finds the literal; it is evaluated ALONE in an empty, timed vm context; the result must materialize to plain JSON data and pass shape validation (unknown fields rejected loud); the statement is blanked line-preservingly so stacks keep script line numbers. +**Meta as data, never evaluated**: the meta block reaches the seam as a plain JSON request field (the tool's schema-validated `meta` parameter) and the engine only shape-validates it, every violation named. This is a host-isolation invariant, not a convenience: evaluating a meta literal host-side — even one contractually "pure", in an empty timed vm context — hands script-controlled getters a host stack with no timeout the moment the result is READ, defeating the exact spin isolation the worker thread buys. **Value boundary**: values leaving the script (meta, hook options, schemas, the return value) go through `materializeFromRealm` — a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying via `Object.defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation; getters are read ordinarily and their RESULT crosses (a throwing read fails loud) — which is also what makes every later postMessage hop total. Values entering the realm (`args`, `agent()` results, hook promises and failures, combinator arrays) are handed over directly as worker-realm values — the script is trusted, so outer prototypes are not a leak; `args` rides the `workerData` structured clone (the caller-isolation copy) and is cloned once more so a script scribbling on it cannot mutate the session's init object. Hook failures are `WorkflowError`s built OUTSIDE the script's context: the combinators recognize fatality by `instanceof` against the engine's own class (unforgeable from the script), and the script-visible consequence — in-script `instanceof Error` is `false` for hook errors; branch on `e.name`/`e.code` — is documented in the engine README. Realm functions (stages, thunks) are called, never materialized. Thrown script values are rendered by a total renderer (stack → message → `String()`, fixed label if rendering throws), so `result` cannot reject. Caps (`maxConcurrentAgents` auto = `min(16, max(1, availableParallelism() - 2))`, `maxTotalAgents` 1000, `maxItemsPerCall` 4096) and timeouts are validated Config, not literals. ### The consumer (dsh-tool-workflow) -A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by a textual `meta.name` sniff (presentation is a pure function of args). The tool description IS the model-facing authoring spec. The usage policy ships with the tool as its own `tool:` prompt section (explicit-ask-only guidance — tool guidance lives in tool plugins, never in the deployment persona); the harness has no ultracode-style effort gate. +A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by the call's `meta.name` parameter (presentation is a pure function of args). The tool description IS the model-facing authoring spec. The usage policy ships with the tool as its own `tool:` prompt section (explicit-ask-only guidance — tool guidance lives in tool plugins, never in the deployment persona); the harness has no ultracode-style effort gate. ### The foundation: structured output on the subagent seam @@ -55,7 +55,7 @@ A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, awai - **In-process `node:vm` execution** (the first cut of this RFC shipped it): mechanically simplest — no RPC, no thread — but `start()` blocks the caller for the script's initial synchronous slice, a synchronous spin past the first await cannot be killed in-process (the vm `timeout` covers only that first slice), and `dispose()` could only ABANDON an unsettling script, leaving the spin on the host loop. Superseded by the worker-thread engine, which keeps the same vm-context script surface while unblocking the host and making termination real. - **Background execution as the default** (CC's shape): deferred; foreground-synchronous matches `dsh-tool-subagent`'s cut, and background semantics should be designed ONCE across bash/subagent/workflow rather than per-tool. - **Workflow-layer JSON parsing for `agent({schema})`**: duplicating a seam concern at one consumer while the seam's capability flag stayed dishonestly `false`. -- **Meta as tool parameters instead of `export const meta`**: zero parsing, but scripts stop being self-contained artifacts and CC-authored scripts stop being drop-in. +- **Meta embedded in the script as `export const meta = {...}`** (CC's exact format; the first cut shipped it): keeps scripts self-contained and CC scripts drop-in, but obtaining meta means evaluating model-written text on the HOST — the shipped extractor ran the literal in an empty timed vm context, yet reading the RESULT still executed script-controlled getters on the host stack outside any timeout, re-opening the host-spin hole the worker thread exists to close. A JSON parameter deletes the scanner, the evaluation, and the hole outright; the cost is that a CC script's meta header must move into the parameter (the body stays drop-in). - **`SchemaSpec` as the outputSchema type**: the author-facing DSL cannot express what arrives as data and cannot be validated against without conversion loss. - **A schema-object library (zod, or the repo's schemastery) for the structured-output subset**: the schema is wire data — plain JSON that crosses the vm realm boundary in `agent({schema})` and lands verbatim in the forced tool's parameters — exactly where live schema objects cannot sit; consuming raw JSON Schema at runtime would need a third-party converter on top (zod core only emits JSON Schema, not the reverse), and it would put a second schema language beside schemastery's config role. - **ajv for value validation**: it validates FULL JSON Schema, so the subset gate — the module's actual point, since every accepted keyword must be one the harness enforces — would remain hand-written regardless; it compiles validators through `new Function`; and it would be dsh-tools' first runtime dependency, all to replace the ~70-line value walker while the path-qualified, every-violation error reporting stays custom either way. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 3794b1d7a7..088147b799 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -283,7 +283,7 @@ todo_write is session-owned state; UIs render the latest todo/write event as a c Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. -The script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. +The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. @@ -301,7 +301,53 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim "properties": { "script": { "type": "string", - "description": "The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)." + "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)." + }, + "meta": { + "type": "object", + "description": "The workflow identity block (plain JSON — never code).", + "properties": { + "name": { + "type": "string", + "description": "Short kebab-case workflow name." + }, + "description": { + "type": "string", + "description": "One-line description of what the workflow does." + }, + "whenToUse": { + "type": "string", + "description": "Optional guidance on when this workflow applies." + }, + "phases": { + "type": "array", + "description": "Optional phase declarations matched by phase() calls.", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The phase title phase() calls match by exact string." + }, + "detail": { + "type": "string", + "description": "Optional one-line description of the phase." + }, + "model": { + "type": "string", + "description": "Optional model override this phase is expected to use." + } + }, + "required": [ + "title" + ] + } + } + }, + "required": [ + "name", + "description" + ] }, "args": { "type": "object", @@ -309,7 +355,8 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim } }, "required": [ - "script" + "script", + "meta" ] } ``` diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts index 22ab21ffc6..7cd1606b47 100644 --- a/packages/workflow/tool-workflow/src/index.ts +++ b/packages/workflow/tool-workflow/src/index.ts @@ -13,9 +13,8 @@ * collection is deferred to the cross-tool background redesign. * * Render intent (decided up front, per the render-intent RFC): a `generic` - * card whose title carries the script's `meta.name`, sniffed textually from - * the args — presentation must be a pure function of `args`, so it cannot ask - * the engine to parse. + * card whose title carries the workflow's `meta.name`, read directly from the + * call's `meta` parameter — presentation is a pure function of `args`. * * Usage policy ships with the tool as a `tool:` system-prompt * section (explicit-ask-only guidance) — tool guidance lives in tool plugins, @@ -58,7 +57,7 @@ type ResolvedConfig = Required */ const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. -The script MUST begin with \`export const meta = {...}\` — a PURE object literal (no variables, calls, or template interpolation) with required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, model?}\`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with \`return \` — the value must be JSON-serializable and is this tool's result. +The workflow's identity rides the \`meta\` parameter as JSON: required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, model?}\`). The \`script\` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO \`export const meta\` statement — meta is a parameter, not code), running with top-level await; end with \`return \` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - \`agent(prompt, opts?): Promise\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), \`model\` (override). Anything else (\`effort\`/\`isolation\`/\`agentType\`) is rejected loudly. @@ -70,20 +69,17 @@ Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.` -type WorkflowCallArgs = { script: string; args?: Record } - -/** Best-effort meta.name sniff for presentation (pure textual; no evaluation). */ -function sniffMetaName(script: string): string | undefined { - const match = /export\s+const\s+meta\s*=\s*\{[^{}]*?name\s*:\s*(['"`])([^'"`\n]{1,64})\1/.exec(script) - return match?.[2] +type WorkflowCallArgs = { + script: string + meta: { name: string; description: string; whenToUse?: string; phases?: { title: string; detail?: string; model?: string }[] } + args?: Record } -/** The pending-state card: a generic card titled by the script's meta name. */ +/** The pending-state card: a generic card titled by the workflow's meta name. */ function presentWorkflowCall(args: WorkflowCallArgs): ToolCallView { - const name = sniffMetaName(args.script) return { card: 'generic', - title: name !== undefined ? `workflow: ${name}` : 'workflow', + title: `workflow: ${args.meta.name}`, rawInput: args.script, } } @@ -139,7 +135,29 @@ export function apply(ctx: Context, config: Config): void { script: { type: 'string', required: true, - description: 'The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `).', + description: 'The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `).', + }, + meta: { + type: 'object', + required: true, + description: 'The workflow identity block (plain JSON — never code).', + properties: { + name: { type: 'string', required: true, description: 'Short kebab-case workflow name.' }, + description: { type: 'string', required: true, description: 'One-line description of what the workflow does.' }, + whenToUse: { type: 'string', description: 'Optional guidance on when this workflow applies.' }, + phases: { + type: 'array', + description: 'Optional phase declarations matched by phase() calls.', + items: { + type: 'object', + properties: { + title: { type: 'string', required: true, description: 'The phase title phase() calls match by exact string.' }, + detail: { type: 'string', description: 'Optional one-line description of the phase.' }, + model: { type: 'string', description: 'Optional model override this phase is expected to use.' }, + }, + }, + }, + }, }, args: { type: 'object', @@ -155,11 +173,12 @@ export function apply(ctx: Context, config: Config): void { throw new Error('workflow tool requires a calling agent (exec.agent was undefined)') } - // Parse failures (SCRIPT_PARSE/META_INVALID) throw synchronously here - // and become isError results via the registry — the model sees the - // violation list and can correct the script. + // Meta/body validation failures (META_INVALID/SCRIPT_PARSE) throw + // synchronously here and become isError results via the registry — the + // model sees the violation list and can correct the call. const run: WorkflowRun = ctx.workflows.start({ script: args.script, + meta: args.meta, ...args.args !== undefined ? { args: args.args } : {}, parent, ...exec.signal ? { signal: exec.signal } : {}, diff --git a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts index dafc39bf46..0585889617 100644 --- a/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts +++ b/packages/workflow/tool-workflow/tests/tool-workflow.spec.ts @@ -55,7 +55,8 @@ async function setup(config?: { toolName?: string; maxResultChars?: number }) { return { ctx, engine, parent } } -const SCRIPT = "export const meta = { name: 'audit', description: 'd' }\nreturn 1" +const SCRIPT = 'return 1' +const META = { name: 'audit', description: 'd' } function execute(ctx: Context, args: unknown, extra?: { agent?: Agent; signal?: AbortSignal }): Promise { return ctx.tools.execute({ @@ -71,9 +72,9 @@ describe('dsh-tool-workflow', () => { it('starts a run with the script/args/parent/signal and renders the completed value', async () => { const { ctx, engine, parent } = await setup() const controller = new AbortController() - const pending = execute(ctx, { script: SCRIPT, args: { files: ['a.ts'] } }, { agent: parent, signal: controller.signal }) + const pending = execute(ctx, { script: SCRIPT, meta: META, args: { files: ['a.ts'] } }, { agent: parent, signal: controller.signal }) await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) - expect(engine.requests[0]).toMatchObject({ script: SCRIPT, args: { files: ['a.ts'] }, parent }) + expect(engine.requests[0]).toMatchObject({ script: SCRIPT, meta: META, args: { files: ['a.ts'] }, parent }) expect(engine.requests[0]!.signal).toBe(controller.signal) engine.settle({ value: { findings: [1, 2] }, stopReason: 'completed', agentsStarted: 7 }) const result = await pending @@ -86,7 +87,7 @@ describe('dsh-tool-workflow', () => { it('maps a non-completed stop reason to an isError result (and still disposes)', async () => { const { ctx, engine, parent } = await setup() - const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent }) await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) engine.settle({ value: null, stopReason: 'error', error: 'script threw: boom', agentsStarted: 2 }) const result = await pending @@ -97,14 +98,14 @@ describe('dsh-tool-workflow', () => { it('reports a cancelled run distinctly (with and without a reason)', async () => { const { ctx, engine, parent } = await setup() - const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent }) await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) engine.settle({ value: null, stopReason: 'cancelled', error: 'user', agentsStarted: 0 }) const result = await pending expect(result.isError).toBe(true) expect((result.content[0] as { text: string }).text).toContain('workflow run was cancelled (user)') - const bare = execute(ctx, { script: SCRIPT }, { agent: parent }) + const bare = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent }) await vi.waitFor(() => { expect(engine.requests.length).toBe(2) }) engine.settle({ value: null, stopReason: 'cancelled', agentsStarted: 0 }) expect(((await bare).content[0] as { text: string }).text.trim().endsWith('cancelled')).toBe(true) @@ -112,7 +113,7 @@ describe('dsh-tool-workflow', () => { it('an error result without a message renders the unknown-error fallback', async () => { const { ctx, engine, parent } = await setup() - const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent }) await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) engine.settle({ value: null, stopReason: 'error', agentsStarted: 0 }) expect(((await pending).content[0] as { text: string }).text).toContain('unknown error') @@ -121,7 +122,7 @@ describe('dsh-tool-workflow', () => { it('cancels the run when exec.signal aborts MID-FLIGHT (the abort bridge)', async () => { const { ctx, engine, parent } = await setup() const controller = new AbortController() - const pending = execute(ctx, { script: SCRIPT }, { agent: parent, signal: controller.signal }) + const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent, signal: controller.signal }) await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) controller.abort() const result = await pending @@ -130,17 +131,17 @@ describe('dsh-tool-workflow', () => { expect(engine.disposed).toBe(1) }) - it('a synchronous engine start throw (parse/meta failure) becomes an isError result', async () => { + it('a synchronous engine start throw (meta/parse failure) becomes an isError result', async () => { const { ctx, engine, parent } = await setup() - engine.startError = new Error('script must begin with `export const meta = {...}`') - const result = await execute(ctx, { script: 'nope' }, { agent: parent }) + engine.startError = new Error('invalid meta: meta.name must be a non-empty string') + const result = await execute(ctx, { script: 'nope', meta: { name: '', description: 'd' } }, { agent: parent }) expect(result.isError).toBe(true) - expect((result.content[0] as { text: string }).text).toContain('must begin with') + expect((result.content[0] as { text: string }).text).toContain('meta.name must be a non-empty string') }) it('requires a calling agent (fails loud without exec.agent)', async () => { const { ctx, engine } = await setup() - const result = await execute(ctx, { script: SCRIPT }) + const result = await execute(ctx, { script: SCRIPT, meta: META }) expect(result.isError).toBe(true) expect((result.content[0] as { text: string }).text).toContain('requires a calling agent') expect(engine.requests.length).toBe(0) @@ -157,7 +158,7 @@ describe('dsh-tool-workflow', () => { const { ctx, engine, parent } = await setup() const controller = new AbortController() controller.abort() - const result = await execute(ctx, { script: SCRIPT }, { agent: parent, signal: controller.signal }) + const result = await execute(ctx, { script: SCRIPT, meta: META }, { agent: parent, signal: controller.signal }) expect(result.isError).toBe(true) expect(engine.cancels).toContain('parent step aborted') expect(engine.disposed).toBe(1) @@ -165,7 +166,7 @@ describe('dsh-tool-workflow', () => { it('truncates an oversized rendered value with a notice (maxResultChars)', async () => { const { ctx, engine, parent } = await setup({ maxResultChars: 40 }) - const pending = execute(ctx, { script: SCRIPT }, { agent: parent }) + const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent }) await vi.waitFor(() => { expect(engine.requests.length).toBe(1) }) engine.settle({ value: { blob: 'x'.repeat(500) }, stopReason: 'completed', agentsStarted: 1 }) const rendered = ((await pending).content[0] as { text: string }).text @@ -193,22 +194,22 @@ describe('dsh-tool-workflow', () => { expect((await ctx.systemPrompt.assemble()).sections.some(s => s.name === 'tool:orchestrate')).toBe(false) }) - it('presents a generic pending card titled by the sniffed meta name, with the script as rawInput', async () => { + it('presents a generic pending card titled by the meta name, with the script as rawInput', async () => { const { ctx } = await setup() const tool = ctx.tools.get('workflow')! - const view = tool.presentCall!({ script: SCRIPT }) + const view = tool.presentCall!({ script: SCRIPT, meta: META }) expect(view).toMatchObject({ card: 'generic', title: 'workflow: audit', rawInput: SCRIPT }) - const anonymous = tool.presentCall!({ script: 'export const meta = {}\nreturn 1' }) - expect(anonymous).toMatchObject({ card: 'generic', title: 'workflow' }) }) it('presentResult keeps the generic card; presentation is pure and replay-safe on malformed args', async () => { const { ctx } = await setup() const tool = ctx.tools.get('workflow')! - expect(tool.presentResult!({ script: SCRIPT }, { content: [], isError: false })).toEqual({ card: 'generic' }) + expect(tool.presentResult!({ script: SCRIPT, meta: META }, { content: [], isError: false })).toEqual({ card: 'generic' }) // defineTool soft-validates presentation args: a malformed logged shape - // falls back to undefined instead of throwing mid-replay. + // (wrong fields entirely, or a call missing its meta) falls back to + // undefined instead of throwing mid-replay. expect(tool.presentCall!({ not: 'the schema' })).toBeUndefined() + expect(tool.presentCall!({ script: SCRIPT })).toBeUndefined() }) it('has the namespace-plugin export shape (no stray default)', () => { @@ -239,7 +240,8 @@ describe('dsh-tool-workflow', () => { const parent = { id: AgentId('caller'), options: {} } as unknown as Agent const controller = new AbortController() const pending = execute(ctx, { - script: "export const meta = { name: 'stuck', description: 'parks forever' }\nawait new Promise(() => {})\nreturn 1", + script: 'await new Promise(() => {})\nreturn 1', + meta: { name: 'stuck', description: 'parks forever' }, }, { agent: parent, signal: controller.signal }) // Give the run a beat to start (past its synchronous slice), then abort. await new Promise(resolve => setTimeout(resolve, 20)) diff --git a/packages/workflow/workflow-workerthread/README.md b/packages/workflow/workflow-workerthread/README.md index 0e763bdee9..25c79ad09c 100644 --- a/packages/workflow/workflow-workerthread/README.md +++ b/packages/workflow/workflow-workerthread/README.md @@ -14,19 +14,19 @@ What the seam guarantees regardless, because benign scripts hit these constantly ## The script contract it executes -- **Meta extraction** (`extractMeta`, host-side): a string/comment-aware brace scanner finds the leading `export const meta` literal (template interpolation rejected — the literal must be pure), evaluates it ALONE in an empty timed vm context, materializes the result to plain JSON data, validates the shape (`name`/`description` required; unknown fields rejected loud), and blanks the statement line-preservingly so error stacks keep the script's own line numbers. +- **Meta as DATA** (`validateMeta`, host-side): the workflow's identity arrives on the start request as plain JSON (the tool carries it as its schema-validated `meta` parameter — never as script text) and is shape-validated loud, every violation named (`name`/`description` required; unknown fields rejected). The engine deliberately evaluates NO script text to obtain meta: an evaluated meta literal could smuggle getters that run on the host outside any vm timeout — the exact spin the worker thread exists to isolate. A body that still opens with a Claude Code-style `export const meta` statement is rejected with a pointed `SCRIPT_PARSE` message. - **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline). - **No ambient APIs**: no timers, filesystem, or Node APIs are injected into the context (absence is API surface, not containment — see the trust premise). ## How a run executes -`start()` extracts and validates the meta HOST-side and parse-checks the body with the identical wrapper the worker compiles (`new vm.Script`, discarded), preserving the seam's synchronous `SCRIPT_PARSE`/`META_INVALID` throws; one redundant parse per run is the deliberate price. It then spawns the worker (`src/worker.ts` unbuilt via an explicit tsx `execArgv`; the sibling `lib/worker.js` bundle when built) with the meta, blanked body, `args`, and worker-side limits as `workerData`. +`start()` shape-validates the meta DATA host-side and parse-checks the body with the identical wrapper the worker compiles (`new vm.Script`, discarded), preserving the seam's synchronous `META_INVALID`/`SCRIPT_PARSE` throws; one redundant parse per run is the deliberate price. It then spawns the worker (`src/worker.ts` unbuilt via an explicit tsx `execArgv`; the sibling `lib/worker.js` bundle when built) with the meta, body, `args`, and worker-side limits as `workerData`. Inside the worker, `runWorkerSession` builds the execution core (hooks, combinators, concurrency semaphore, caps, fatal-error discipline) over a **child port**: `agent()` sends `child-start` and the host starts the child on `ctx.subagents` (parent attribution, the shared per-run abort signal, `outputSchema`/`model` pass-through), replying with the child id, its settlement (a JSON projection; an infrastructure REJECTION crosses as `child-failed` and stays the fatal `AGENT_RESULT`), and dispose acks. Observer narration (`phase`/`log`/`agent-start`/`agent-end`) crosses as messages and re-emits as the seam's `workflow/*` events. A **ready→go handshake** gates the body: a cancellation racing worker boot arrives before `go`, so a run cancelled before start never executes the body at all. ## The value boundary -Values LEAVING the script (the meta literal, hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into plain containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Getters are read ordinarily — the RESULT is what crosses; a read that throws fails loud. Values ENTERING the realm (`args`, `agent()` results, hook promises and their failures, combinator arrays) are handed over directly as worker-realm values — the script is trusted, so outer prototypes are not a leak; `args` is cloned once at start so a script scribbling on it cannot mutate the caller's object. One script-visible consequence: an error thrown by a hook is built OUTSIDE the script's vm context, so `e instanceof Error` inside the script is `false` — branch on `e.name`/`e.code` instead (the combinators recognize fatality by `instanceof` against their own realm's class, which a script-built object can never pass, so fatal-vs-null cannot be forged or dissolved). +Values LEAVING the script (hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into plain containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Getters are read ordinarily — the RESULT is what crosses; a read that throws fails loud; both run in the WORKER, never on the host. Values ENTERING the realm (`args`, `agent()` results, hook promises and their failures, combinator arrays) are handed over directly as worker-realm values — the script is trusted, so outer prototypes are not a leak; `args` is cloned once at start so a script scribbling on it cannot mutate the caller's object. One script-visible consequence: an error thrown by a hook is built OUTSIDE the script's vm context, so `e instanceof Error` inside the script is `false` — branch on `e.name`/`e.code` instead (the combinators recognize fatality by `instanceof` against their own realm's class, which a script-built object can never pass, so fatal-vs-null cannot be forged or dissolved). ## Cancellation, death, disposal @@ -44,5 +44,5 @@ A worker that dies unexpectedly (an OOM, a script reaching `process.exit` throug | `maxConcurrentAgents` | `0` (auto) | Concurrent `agent()` ceiling; `0` resolves to `min(16, max(1, cores - 2))`. | | `maxTotalAgents` | `1000` | Total `agent()` calls one run may start (runaway-loop backstop). | | `maxItemsPerCall` | `4096` | Items accepted by one `parallel()`/`pipeline()` call. | -| `syncTimeoutMs` | `5000` | vm timeout for the initial synchronous slice (in the worker) and the host-side meta evaluation. | +| `syncTimeoutMs` | `5000` | vm timeout for the script's initial synchronous slice (in the worker). | | `disposeGraceMs` | `5000` | How long a cancelled run may stay unsettled before force-settle + terminate; also bounds `dispose()`. | diff --git a/packages/workflow/workflow-workerthread/src/index.ts b/packages/workflow/workflow-workerthread/src/index.ts index 538252d90a..e0b8caf3fb 100644 --- a/packages/workflow/workflow-workerthread/src/index.ts +++ b/packages/workflow/workflow-workerthread/src/index.ts @@ -47,10 +47,10 @@ import z from 'schemastery' import WorkflowService, { WorkflowError, WorkflowRunId } from '@deepseek-ai/dsh-workflow' import type { WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow' import { WorkerRun } from './host.ts' -import { extractMeta } from './meta.ts' +import { validateMeta } from './meta.ts' import type { WorkerInit, WorkerLimits } from './types.ts' -export { extractMeta, type ExtractedScript } from './meta.ts' +export { validateMeta } from './meta.ts' export { HostToWorkerType, WorkerToHostType } from './protocol.ts' export type { HostToWorkerMessage, HostToWorkerPayloads, WorkerToHostMessage, WorkerToHostPayloads } from './protocol.ts' export { materializeFromRealm, MaterializeError } from './realm.ts' @@ -75,7 +75,7 @@ export interface Config { maxTotalAgents?: number /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */ maxItemsPerCall?: number - /** vm timeout for the initial synchronous slice (inside the worker) AND the host-side meta evaluation (default 5000 ms). */ + /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */ syncTimeoutMs?: number /** * How long after a cancellation an unsettled script may keep running before @@ -87,13 +87,21 @@ export interface Config { type ResolvedConfig = Required +/** A body that still carries the Claude Code-style meta header (meta rides the seam as data here). */ +const META_STATEMENT = /^\s*export\s+const\s+meta\b/ + /** * Parse-check the body with the SAME wrapper the worker-side runtime * compiles, so `start()` keeps the seam's synchronous `SCRIPT_PARSE` throw * (the worker's own compile happens a thread away, after `start()` returned). - * One redundant parse per run, bought deliberately for the contract. + * One redundant parse per run, bought deliberately for the contract. A body + * opening with `export const meta` gets a pointed message instead of the + * wrapper's bare SyntaxError — the model's likeliest authoring slip. */ function assertBodyParses(body: string, name: string): void { + if (META_STATEMENT.test(body)) { + throw new WorkflowError('workflow meta rides the `meta` request field, not the script: remove the `export const meta = {...}` statement from the body', 'SCRIPT_PARSE') + } try { // Parse only — the script object is discarded, nothing executes. void new vm.Script(`(async () => {\n${body}\n})()`, { filename: `workflow:${name}`, lineOffset: -1 }) @@ -130,17 +138,18 @@ export class WorkerWorkflowEngine extends WorkflowService { } /** - * Parse and execute a workflow script in a fresh worker thread. Throws - * {@link WorkflowError} synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a - * script that cannot begin; once a run is returned, every failure resolves - * through `result.stopReason` instead. - * @param request - the script, its `args`, the parent agent, and an - * optional cancel signal. + * Validate and execute a workflow script in a fresh worker thread. Throws + * {@link WorkflowError} synchronously (`META_INVALID` for a malformed meta + * block, `SCRIPT_PARSE` for a body that does not compile) for a request + * that cannot begin; once a run is returned, every failure resolves through + * `result.stopReason` instead. + * @param request - the script body, its meta data and `args`, the parent + * agent, and an optional cancel signal. * @returns the live run (its `result` resolves when the script settles). */ start(request: WorkflowStartRequest): WorkflowRun { - const { meta, body } = extractMeta(request.script, this.config.syncTimeoutMs) - assertBodyParses(body, meta.name) + const meta = validateMeta(request.meta) + assertBodyParses(request.script, meta.name) const id = WorkflowRunId(randomUUID()) // The event payloads and the run handle get SEPARATE meta clones: a // listener mutating its snapshot must not corrupt the holder's view. @@ -155,7 +164,7 @@ export class WorkerWorkflowEngine extends WorkflowService { } const init: WorkerInit = { meta, - body, + body: request.script, ...request.args !== undefined ? { args: request.args } : {}, limits, } diff --git a/packages/workflow/workflow-workerthread/src/meta.ts b/packages/workflow/workflow-workerthread/src/meta.ts index e818bc6f00..848a4fc9b1 100644 --- a/packages/workflow/workflow-workerthread/src/meta.ts +++ b/packages/workflow/workflow-workerthread/src/meta.ts @@ -1,100 +1,24 @@ /** - * Meta-block extraction: turn a Claude Code-format workflow script — - * `export const meta = {...}` followed by a plain-JS body — into a validated - * {@link WorkflowMeta} plus the body with the meta statement blanked - * line-preservingly (error stacks keep the script's own line numbers). - * - * The scanner is a small string/comment-aware brace matcher, not a JS parser: - * it only has to find the END of the meta object literal, and the literal is - * contractually PURE (no interpolation, no computed values). Template strings - * are tolerated as plain quotes but `${` inside one is rejected up front — - * interpolation is where "literal" stops being checkable by evaluation. The - * extracted text is then evaluated ALONE in an empty, timed vm context (a - * non-literal reference throws there; an expression can still RUN, so the - * result — not the source — is the contract: it must materialize to plain - * JSON data and pass the shape validation). + * Meta validation: check the caller-provided {@link WorkflowMeta} DATA against + * the shape contract and reject everything else loud, every violation named. + * Meta arrives as plain JSON through the seam (the model-facing tool carries + * it as a schema-validated object parameter) — the engine never evaluates + * script text to obtain it, so no script-controlled code can run on the host + * here (an evaluated meta literal could smuggle getters that spin the host + * outside any vm timeout, the exact escape the worker thread exists to + * prevent). * * @module @deepseek-ai/dsh-workflow-workerthread/meta */ -import * as vm from 'node:vm' import { WorkflowError } from '@deepseek-ai/dsh-workflow' import type { WorkflowMeta, WorkflowPhase } from '@deepseek-ai/dsh-workflow' -import { materializeFromRealm, MaterializeError, renderThrown } from './realm.ts' -/** The result of {@link extractMeta}: the validated meta and the runnable body. */ -export interface ExtractedScript { - meta: WorkflowMeta - /** The script with the meta statement blanked (newlines preserved). */ - body: string -} - -/** - * Scan `source` from `start` (an opening `{`) to its matching `}`, aware of - * string literals (`'`/`"`/backtick, with escapes) and comments. Returns the - * index AFTER the closing brace. Throws `SCRIPT_PARSE` on template - * interpolation (`${` inside a backtick string) or an unterminated literal. - */ -function scanObjectLiteral(source: string, start: number): number { - let depth = 0 - let index = start - while (index < source.length) { - const ch = source.charAt(index) - if (ch === '/' && source[index + 1] === '/') { - const end = source.indexOf('\n', index) - index = end === -1 ? source.length : end + 1 - continue - } - if (ch === '/' && source[index + 1] === '*') { - const end = source.indexOf('*/', index + 2) - if (end === -1) throw new WorkflowError('meta block has an unterminated comment', 'SCRIPT_PARSE') - index = end + 2 - continue - } - if (ch === '\'' || ch === '"' || ch === '`') { - index = scanString(source, index, ch) - continue - } - if (ch === '{' || ch === '[') depth += 1 - if (ch === '}' || ch === ']') { - depth -= 1 - if (depth === 0) return index + 1 - } - index += 1 - } - throw new WorkflowError('meta block is not a balanced object literal', 'SCRIPT_PARSE') -} - -/** Scan past one string literal starting at `start` (the quote char); returns the index after the closing quote. */ -function scanString(source: string, start: number, quote: string): number { - let index = start + 1 - while (index < source.length) { - const ch = source.charAt(index) - if (ch === '\\') { - index += 2 - continue - } - if (quote === '`' && ch === '$' && source[index + 1] === '{') { - throw new WorkflowError('template interpolation (`${...}`) is not allowed in the meta block — meta must be a pure literal', 'SCRIPT_PARSE') - } - if (ch === quote) return index + 1 - index += 1 - } - throw new WorkflowError('meta block has an unterminated string literal', 'SCRIPT_PARSE') -} - -/** Replace `[from, to)` of `source` with whitespace, preserving every newline (line numbers survive). */ -function blankSpan(source: string, from: number, to: number): string { - const blanked = source.slice(from, to).replace(/[^\n]/g, ' ') - return source.slice(0, from) + blanked + source.slice(to) -} - -/** Collect shape violations for an evaluated meta value (already materialized to host JSON data). */ +/** Collect shape violations for a meta value (plain JSON data by the seam contract). */ function validateMetaShape(meta: unknown): { meta?: WorkflowMeta; violations: string[] } { const violations: string[] = [] - /* v8 ignore next 3 -- defensive: the scanner only extracts a brace-delimited literal, which always evaluates to a plain object */ if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) { - return { violations: ['meta must be an object literal'] } + return { violations: ['meta must be an object'] } } const record = meta as Record const known = new Set(['name', 'description', 'whenToUse', 'phases']) @@ -143,97 +67,19 @@ function validateMetaShape(meta: unknown): { meta?: WorkflowMeta; violations: st } } -/** `export const meta =`, anchored AFTER {@link skipLeadingTrivia} — its quantifiers cannot backtrack ambiguously. */ -const META_HEAD = /^export\s+const\s+meta\s*=\s*/ - /** - * Index just past the leading trivia: whitespace and `//` / `/*`-style - * comments. A hand-rolled character scan, NOT a prefix regex — an - * all-alternation prefix (`\s*(?:comment|\s+)*`) partitions a whitespace run - * ambiguously and backtracks EXPONENTIALLY when the match ultimately fails, - * so a near-miss script (a comment header, then a forgotten `export`) would - * spin the host synchronously inside `start()`, where no vm timeout applies. - * The near-miss must fail fast into `SCRIPT_PARSE` instead — that error is - * the model's retry signal. + * Validate a caller-provided meta value against the {@link WorkflowMeta} + * contract. Throws `META_INVALID` naming every violation (unknown fields, + * missing/mistyped `name`/`description`, malformed `phases`); the returned + * meta is a NORMALIZED copy built from the validated fields, so the engine + * never aliases the caller's object. + * @param value - the meta data from the start request (plain JSON by the seam contract). + * @returns the validated, normalized meta block. */ -function skipLeadingTrivia(source: string): number { - let index = 0 - while (index < source.length) { - const ch = source.charAt(index) - if (/\s/.test(ch)) { - index += 1 - continue - } - if (ch === '/' && source[index + 1] === '/') { - const end = source.indexOf('\n', index) - if (end === -1) return source.length - index = end + 1 - continue - } - if (ch === '/' && source[index + 1] === '*') { - const end = source.indexOf('*/', index + 2) - if (end === -1) throw new WorkflowError('script has an unterminated comment before the meta block', 'SCRIPT_PARSE') - index = end + 2 - continue - } - break - } - return index -} - -/** - * Extract and validate the leading `export const meta = {...}` statement. - * Throws {@link WorkflowError} — `SCRIPT_PARSE` when the statement is missing - * or unscannable, `META_INVALID` when the literal evaluates to something - * outside the meta contract (non-JSON data, wrong shape, unknown fields). - * @param script - the full script text. - * @param evalTimeoutMs - the vm timeout for evaluating the extracted literal. - * @returns the validated meta and the line-preservingly blanked body. - */ -export function extractMeta(script: string, evalTimeoutMs: number): ExtractedScript { - const triviaEnd = skipLeadingTrivia(script) - const match = META_HEAD.exec(script.slice(triviaEnd)) - if (!match) { - throw new WorkflowError('script must begin with `export const meta = {...}` (leading comments allowed)', 'SCRIPT_PARSE') - } - const literalStart = triviaEnd + match[0].length - if (script[literalStart] !== '{') { - throw new WorkflowError('`export const meta =` must be followed by an object literal', 'SCRIPT_PARSE') - } - const literalEnd = scanObjectLiteral(script, literalStart) - const literal = script.slice(literalStart, literalEnd) - - let evaluated: unknown - try { - // An EMPTY context: any non-literal reference (a variable, a call) throws - // here. The result — data only — is what the contract checks; a getter or - // IIFE can still run, which is why the timeout and the materialization - // below are part of the same boundary. - evaluated = vm.runInNewContext(`(${literal})`, undefined, { timeout: evalTimeoutMs }) - } catch (error: unknown) { - throw new WorkflowError( - `meta block failed to evaluate as a pure literal: ${renderThrown(error)}`, - 'META_INVALID', - { cause: error }, - ) - } - let data: unknown - try { - data = materializeFromRealm(evaluated, 'meta') - } catch (error: unknown) { - /* v8 ignore next -- defensive rethrow arm: materializeFromRealm only throws MaterializeError */ - if (!(error instanceof MaterializeError)) throw error - throw new WorkflowError(`meta block is not pure JSON data — ${error.message}`, 'META_INVALID', { cause: error }) - } - const { meta, violations } = validateMetaShape(data) +export function validateMeta(value: unknown): WorkflowMeta { + const { meta, violations } = validateMetaShape(value) if (meta === undefined) { - throw new WorkflowError(`invalid meta block: ${violations.join('; ')}`, 'META_INVALID') + throw new WorkflowError(`invalid meta: ${violations.join('; ')}`, 'META_INVALID') } - - // Blank the whole statement (including a trailing semicolon, if any) so the - // body compiles standalone with its original line numbers. - let statementEnd = literalEnd - while (statementEnd < script.length && (script[statementEnd] === ' ' || script[statementEnd] === '\t')) statementEnd += 1 - if (script[statementEnd] === ';') statementEnd += 1 - return { meta, body: blankSpan(script, 0, statementEnd) } + return meta } diff --git a/packages/workflow/workflow-workerthread/src/runtime.ts b/packages/workflow/workflow-workerthread/src/runtime.ts index 28450977c3..645a61b6c4 100644 --- a/packages/workflow/workflow-workerthread/src/runtime.ts +++ b/packages/workflow/workflow-workerthread/src/runtime.ts @@ -109,7 +109,7 @@ export class WorkflowExecution { // wrapper, so under one Node version this throw is unreachable in // production — the session still maps it to an error result defensively. // lineOffset compensates for the wrapper line, so stack traces carry the - // script's own line numbers (the meta statement was blanked, not removed). + // script's own line numbers. try { this.compiled = new vm.Script(`(async () => {\n${body}\n})()`, { filename: `workflow:${meta.name}`, diff --git a/packages/workflow/workflow-workerthread/src/types.ts b/packages/workflow/workflow-workerthread/src/types.ts index 329523ffc8..a80b126a2d 100644 --- a/packages/workflow/workflow-workerthread/src/types.ts +++ b/packages/workflow/workflow-workerthread/src/types.ts @@ -30,9 +30,9 @@ export interface WorkerLimits { /** The `workerData` payload one run is initialized with (host → worker, once, at spawn). */ export interface WorkerInit { - /** The validated meta block (extracted host-side). */ + /** The validated meta block (plain data off the start request, validated host-side). */ meta: WorkflowMeta - /** The script body with the meta statement blanked (host-side `extractMeta`). */ + /** The plain-JS script body, exactly as the start request carried it. */ body: string /** The run's `args` value; the workerData structured clone is the copy that isolates the caller. */ args?: unknown diff --git a/packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts b/packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts index d541b4c0ff..545be831f6 100644 --- a/packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts +++ b/packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts @@ -34,7 +34,8 @@ const ctx = new Context() await ctx.plugin(SubagentService) await ctx.plugin(WorkerWorkflowEngine, {}) const run = ctx.workflows.start({ - script: "export const meta = { name: 'built-smoke', description: 'built worker smoke' }\\nreturn 6 * 7", + script: 'return 6 * 7', + meta: { name: 'built-smoke', description: 'built worker smoke' }, // A zero-agent script never touches the provider, so a bare id suffices. parent: { id: 'built-smoke-parent', options: {} }, }) diff --git a/packages/workflow/workflow-workerthread/tests/integration.spec.ts b/packages/workflow/workflow-workerthread/tests/integration.spec.ts index ae58a536f8..d6e8237804 100644 --- a/packages/workflow/workflow-workerthread/tests/integration.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/integration.spec.ts @@ -50,8 +50,8 @@ describe('dsh-workflow-workerthread over the real in-process stack', () => { const childIds: string[] = [] ctx.on('workflow/agent-start', (_info, agent) => { childIds.push(agent.childId) }) const run = ctx.workflows.start({ - script: `export const meta = { name: 'integration', description: 'plain + structured children' } -phase('Read') + meta: { name: 'integration', description: 'plain + structured children' }, + script: `phase('Read') const prose = await agent('read the repo') phase('Judge') const judged = await agent('judge: ' + prose, { @@ -78,8 +78,8 @@ return { prose, verdict: judged.verdict, confidence: judged.confidence }`, textResponse('still prose after the nudge'), ]) const run = ctx.workflows.start({ - script: `export const meta = { name: 'null-path', description: 'schema failure maps to null' } -const judged = await agent('judge it', { schema: { type: 'object', properties: { v: { type: 'string' } } } }) + meta: { name: 'null-path', description: 'schema failure maps to null' }, + script: `const judged = await agent('judge it', { schema: { type: 'object', properties: { v: { type: 'string' } } } }) return { got: judged === null ? 'null' : 'value' }`, parent, }) diff --git a/packages/workflow/workflow-workerthread/tests/meta.spec.ts b/packages/workflow/workflow-workerthread/tests/meta.spec.ts index a1c622e3fc..37b86440be 100644 --- a/packages/workflow/workflow-workerthread/tests/meta.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/meta.spec.ts @@ -1,182 +1,88 @@ import { describe, expect, it } from 'vitest' import { WorkflowError } from '@deepseek-ai/dsh-workflow' -import { extractMeta } from '../src/meta.ts' +import { validateMeta } from '../src/meta.ts' -const TIMEOUT = 1000 - -/** Extract and expect success. */ -function ok(script: string) { - return extractMeta(script, TIMEOUT) -} - -/** The WorkflowError a bad script produces (throws if it extracts cleanly). */ -function bad(script: string): WorkflowError { +/** Assert a META_INVALID throw whose message matches every given fragment. */ +function expectInvalid(value: unknown, ...fragments: string[]): void { + let thrown: unknown try { - extractMeta(script, TIMEOUT) + validateMeta(value) } catch (error: unknown) { - if (error instanceof WorkflowError) return error - throw error + thrown = error + } + expect(thrown).toBeInstanceOf(WorkflowError) + expect((thrown as WorkflowError).code).toBe('META_INVALID') + for (const fragment of fragments) { + expect((thrown as WorkflowError).message).toContain(fragment) } - throw new Error('expected extraction to fail') } -describe('extractMeta', () => { - it('extracts a full meta block and blanks the statement line-preservingly', () => { - const script = `export const meta = { - name: 'audit-routes', - description: 'Audit every route', - whenToUse: 'when auditing', - phases: [{ title: 'Scan', detail: 'find files' }, { title: 'Fix', model: 'deepseek-v4-pro' }], -} -const x = 1 -return x` - const { meta, body } = ok(script) - expect(meta).toEqual({ - name: 'audit-routes', - description: 'Audit every route', - whenToUse: 'when auditing', - phases: [{ title: 'Scan', detail: 'find files' }, { title: 'Fix', model: 'deepseek-v4-pro' }], +describe('validateMeta', () => { + it('accepts a minimal meta and returns a normalized copy (no aliasing of the input)', () => { + const input = { name: 'audit', description: 'audit the repo' } + const meta = validateMeta(input) + expect(meta).toEqual({ name: 'audit', description: 'audit the repo' }) + expect(meta).not.toBe(input) + input.name = 'mutated' + expect(meta.name).toBe('audit') + }) + + it('accepts the full shape and rebuilds phases entry by entry', () => { + const meta = validateMeta({ + name: 'migrate', + description: 'migrate call sites', + whenToUse: 'large mechanical sweeps', + phases: [ + { title: 'Discover' }, + { title: 'Transform', detail: 'one agent per file', model: 'deepseek-v4-pro' }, + ], + }) + expect(meta).toEqual({ + name: 'migrate', + description: 'migrate call sites', + whenToUse: 'large mechanical sweeps', + phases: [ + { title: 'Discover' }, + { title: 'Transform', detail: 'one agent per file', model: 'deepseek-v4-pro' }, + ], }) - // Same line count; the statement's characters blanked; the body intact. - expect(body.split('\n').length).toBe(script.split('\n').length) - expect(body.split('\n')[6]).toBe('const x = 1') - expect(body).not.toContain('export') }) - it('allows leading line and block comments before the meta statement', () => { - const script = `// a workflow -/* multi - line */ -export const meta = { name: 'x', description: 'y' } -return 1` - expect(ok(script).meta.name).toBe('x') + it('rejects non-object values loud', () => { + expectInvalid(undefined, 'meta must be an object') + expectInvalid('a string', 'meta must be an object') + expectInvalid(null, 'meta must be an object') + expectInvalid([{ name: 'x', description: 'd' }], 'meta must be an object') }) - it('handles braces inside strings and comments while scanning', () => { - const script = `export const meta = { - name: 'tricky', // } not a close { - /* } also not } */ - description: "has { braces } and 'quotes'", -} -return 2` - expect(ok(script).meta.description).toBe("has { braces } and 'quotes'") + it('rejects unknown fields by name (accepted-then-ignored is banned)', () => { + expectInvalid({ name: 'x', description: 'd', color: 'red' }, 'meta.color is not a recognized field') }) - it('tolerates template-quoted strings WITHOUT interpolation, escapes included', () => { - const script = 'export const meta = { name: `plain`, description: `esc \\` tick` }\nreturn 1' - expect(ok(script).meta.name).toBe('plain') + it('rejects missing or mistyped name/description/whenToUse', () => { + expectInvalid({ description: 'd' }, 'meta.name must be a non-empty string') + expectInvalid({ name: '', description: 'd' }, 'meta.name must be a non-empty string') + expectInvalid({ name: 'x' }, 'meta.description must be a non-empty string') + expectInvalid({ name: 'x', description: 42 }, 'meta.description must be a non-empty string') + expectInvalid({ name: 'x', description: 'd', whenToUse: 3 }, 'meta.whenToUse must be a string') }) - it('consumes a trailing semicolon after the literal, spaces included', () => { - const { body } = ok("export const meta = { name: 'x', description: 'y' };\nreturn 1") - expect(body).not.toContain(';') - expect(body.split('\n')[1]).toBe('return 1') - const spaced = ok("export const meta = { name: 'x', description: 'y' } ;\nreturn 1") - expect(spaced.body).not.toContain(';') + it('rejects malformed phases, entry by entry', () => { + expectInvalid({ name: 'x', description: 'd', phases: 'Scan' }, 'meta.phases must be an array') + expectInvalid({ name: 'x', description: 'd', phases: ['Scan'] }, 'meta.phases[0] must be an object') + expectInvalid({ name: 'x', description: 'd', phases: [{ title: '' }] }, 'meta.phases[0].title must be a non-empty string') + expectInvalid({ name: 'x', description: 'd', phases: [{ title: 'Scan', order: 1 }] }, 'meta.phases[0].order is not a recognized field') + expectInvalid({ name: 'x', description: 'd', phases: [{ title: 'Scan', detail: 9 }] }, 'meta.phases[0].detail must be a string') + expectInvalid({ name: 'x', description: 'd', phases: [{ title: 'Scan', model: 9 }] }, 'meta.phases[0].model must be a string') }) - it('rejects a script that does not begin with the meta statement (SCRIPT_PARSE)', () => { - expect(bad('const a = 1').code).toBe('SCRIPT_PARSE') - expect(bad('').code).toBe('SCRIPT_PARSE') - expect(bad('export const meta = [1]').code).toBe('SCRIPT_PARSE') - }) - - it('a near-miss prefix (comment header + whitespace, then no `export`) fails FAST as SCRIPT_PARSE', () => { - // Regression: the previous all-alternation prefix regex backtracked - // exponentially on exactly this shape (~×2 per extra whitespace char once - // the match fails), spinning the host synchronously inside start(). The - // linear trivia scan must reject it in effectively zero time. - const nearMiss = `// deep-audit workflow: reviews every route handler\n${' \n'.repeat(40)}/* second header block */\n${' '.repeat(200)}\nconst meta = { name: 'x', description: 'y' }\n` - const started = Date.now() - expect(bad(nearMiss).code).toBe('SCRIPT_PARSE') - expect(Date.now() - started).toBeLessThan(1000) - }) - - it('an unterminated block comment BEFORE the meta statement is SCRIPT_PARSE', () => { - const error = bad('/* never closed\nexport const meta = { name: "x", description: "y" }') - expect(error.code).toBe('SCRIPT_PARSE') - expect(error.message).toContain('unterminated comment') - }) - - it('a line comment running to EOF leaves no meta statement (SCRIPT_PARSE)', () => { - expect(bad('// only a comment, no newline').code).toBe('SCRIPT_PARSE') - }) - - it('rejects template interpolation in the meta block as impure (SCRIPT_PARSE)', () => { - const error = bad('export const meta = { name: `w-${1}`, description: "d" }\nreturn 1') - expect(error.code).toBe('SCRIPT_PARSE') - expect(error.message).toContain('pure literal') - }) - - it('rejects unbalanced literals, unterminated strings, and unterminated comments (SCRIPT_PARSE)', () => { - expect(bad('export const meta = { name: "x", description: "y"').code).toBe('SCRIPT_PARSE') - expect(bad('export const meta = { name: "x').code).toBe('SCRIPT_PARSE') - expect(bad('export const meta = { /* open').code).toBe('SCRIPT_PARSE') - // A line comment running to EOF (no newline) leaves the literal unbalanced. - expect(bad('export const meta = { name: "x" // eof comment').code).toBe('SCRIPT_PARSE') - }) - - it('rejects a literal referencing variables or calls (META_INVALID via the empty realm)', () => { - const error = bad('export const meta = { name: someVariable, description: "d" }\nreturn 1') - expect(error.code).toBe('META_INVALID') - expect(error.message).toContain('pure literal') - expect(bad('export const meta = { name: compute(), description: "d" }').code).toBe('META_INVALID') - }) - - it('rejects a literal evaluating to non-JSON data (META_INVALID via materialization)', () => { - const error = bad('export const meta = { name: "x", description: "d", whenToUse: () => 1 }') - expect(error.code).toBe('META_INVALID') - expect(error.message).toContain('JSON data') - }) - - it('a meta expression that THROWS maps to META_INVALID carrying the rendered value', () => { - const error = bad('export const meta = { name: (() => { throw "nope" })(), description: "d" }\nreturn 1') - expect(error.code).toBe('META_INVALID') - expect(error.message).toContain('pure literal') - expect(error.message).toContain('nope') - }) - - it('a spinning meta expression dies by the eval timeout', () => { - try { - extractMeta('export const meta = { name: (() => { while (true) {} })(), description: "d" }', 50) - throw new Error('expected the extraction to time out') - } catch (error: unknown) { - expect(error).toBeInstanceOf(WorkflowError) - expect((error as WorkflowError).code).toBe('META_INVALID') - expect((error as WorkflowError).message.toLowerCase()).toContain('timed out') - } - }) - - it('rejects shape violations with EVERY violation listed (META_INVALID)', () => { - const error = bad('export const meta = { description: 7, bogus: 1 }\nreturn 1') - expect(error.code).toBe('META_INVALID') - expect(error.message).toContain('meta.name must be a non-empty string') - expect(error.message).toContain('meta.description must be a non-empty string') - expect(error.message).toContain('meta.bogus is not a recognized field') - }) - - it('rejects malformed whenToUse and phases shapes precisely', () => { - expect(bad('export const meta = { name: "x", description: "d", whenToUse: 3 }').message) - .toContain('meta.whenToUse must be a string') - expect(bad('export const meta = { name: "x", description: "d", phases: "no" }').message) - .toContain('meta.phases must be an array') - expect(bad('export const meta = { name: "x", description: "d", phases: [3] }').message) - .toContain('meta.phases[0] must be an object') - expect(bad('export const meta = { name: "x", description: "d", phases: [{}] }').message) - .toContain('meta.phases[0].title must be a non-empty string') - expect(bad('export const meta = { name: "x", description: "d", phases: [{ title: "t", extra: 1 }] }').message) - .toContain('meta.phases[0].extra is not a recognized field') - expect(bad('export const meta = { name: "x", description: "d", phases: [{ title: "t", detail: 1 }] }').message) - .toContain('meta.phases[0].detail must be a string') - expect(bad('export const meta = { name: "x", description: "d", phases: [{ title: "t", model: 1 }] }').message) - .toContain('meta.phases[0].model must be a string') - }) - - it('stops scanning at the balanced literal — trailing expression text stays in the body', () => { - // The scanner extracts exactly `{ valueOf: null }`; the ` && 3` is body - // text (which would fail compilation later, but extraction sees only the - // literal and reports its unknown field). - expect(bad('export const meta = { valueOf: null } && 3').message) - .toContain('meta.valueOf is not a recognized field') + it('names EVERY violation in one throw, not just the first', () => { + expectInvalid( + { description: 7, extra: true, phases: [{ title: 'Scan' }, 'bad'] }, + 'meta.extra is not a recognized field', + 'meta.name must be a non-empty string', + 'meta.description must be a non-empty string', + 'meta.phases[1] must be an object', + ) }) }) diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts index 76cfd73d33..6353868a02 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts @@ -42,12 +42,12 @@ async function harness(): Promise { return built } -const SCRIPT = `export const meta = { +const META = { name: 'e2e-worker-arithmetic', description: 'two real children through a worker thread: one prose, one structured', phases: [{ title: 'Ask' }, { title: 'Judge' }], } -phase('Ask') +const SCRIPT = `phase('Ask') log('asking the prose child') const prose = await agent('Reply with exactly one short sentence: what is 2 + 2?') phase('Judge') @@ -76,7 +76,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('worker workflow engine with-key }) } - const run = ctx.workflows.start({ script: SCRIPT, parent: parentHandle.agent }) + const run = ctx.workflows.start({ script: SCRIPT, meta: META, parent: parentHandle.agent }) const result = await run.result await run.dispose() diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index 20911d052e..378dd6ecf6 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -5,7 +5,7 @@ import { AgentId } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import SubagentService from '@deepseek-ai/dsh-subagent' import type { SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent' -import type { WorkflowResult, WorkflowResultInfo, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' +import type { WorkflowMeta, WorkflowResult, WorkflowResultInfo, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' import * as workerEngineModule from '../src/index.ts' import WorkerWorkflowEngine, { type Config } from '../src/index.ts' @@ -104,14 +104,14 @@ async function setup(options?: SetupOptions) { return { ctx, provider, parent: fakeParent() } } -/** Wrap a body in the minimal valid meta header. */ -function script(body: string, metaExtra = ''): string { - return `export const meta = { name: 'test-flow', description: 'a test workflow'${metaExtra} }\n${body}` +/** The standard test meta plus a body, spread into a start request. */ +function scripted(body: string, metaExtra?: Partial): { script: string; meta: WorkflowMeta } { + return { script: body, meta: { name: 'test-flow', description: 'a test workflow', ...metaExtra } } } /** Start + await one run, disposing on the way out. */ -async function run(ctx: Context, parent: Agent, source: string, args?: unknown): Promise { - const handle = ctx.workflows.start({ script: source, parent, ...args !== undefined ? { args } : {} }) +async function run(ctx: Context, parent: Agent, source: { script: string; meta: WorkflowMeta }, args?: unknown): Promise { + const handle = ctx.workflows.start({ ...source, parent, ...args !== undefined ? { args } : {} }) try { return await handle.result } finally { @@ -127,13 +127,13 @@ describe('dsh-workflow-workerthread', () => { for (const name of ['workflow/start', 'workflow/phase', 'workflow/log', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) { ctx.on(name, (...payload: unknown[]) => { events.push([name, payload]) }) } - const result = await run(ctx, parent, script(` + const result = await run(ctx, parent, scripted(` phase('Scan') log('starting with ' + args.files.length + ' files') const answers = await pipeline(args.files, (prev, item) => agent('read ' + item)) phase('Report') return { answers, count: args.files.length } - `, ", phases: [{ title: 'Scan' }, { title: 'Report' }]"), { files: ['a.ts', 'b.ts'] }) + `, { phases: [{ title: 'Scan' }, { title: 'Report' }] }), { files: ['a.ts', 'b.ts'] }) expect(result.stopReason).toBe('completed') expect(result.agentsStarted).toBe(2) @@ -156,7 +156,7 @@ describe('dsh-workflow-workerthread', () => { const { ctx, parent, provider } = await setup({ reply: () => ({ output: [], structured: { files: ['x.ts', 'y.ts'] }, stopReason: 'completed' }), }) - const result = await run(ctx, parent, script(` + const result = await run(ctx, parent, scripted(` const found = await agent('list files', { model: 'deepseek-v4-pro', schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'] } }) return { first: found.files[0], count: found.files.length } `)) @@ -172,14 +172,14 @@ describe('dsh-workflow-workerthread', () => { it('a fatal hook error inside the worker kills the script and reports the error', async () => { const { ctx, parent } = await setup() - const result = await run(ctx, parent, script("return await parallel([() => agent('x', { isolation: 'worktree' })])")) + const result = await run(ctx, parent, scripted("return await parallel([() => agent('x', { isolation: 'worktree' })])")) expect(result.stopReason).toBe('error') expect(result.error).toContain('"isolation" is deferred') }) it('a provider start failure crosses back as a fatal AGENT_START error', async () => { const { ctx, parent } = await setup({ config: { provider: 'nonexistent' } }) - const result = await run(ctx, parent, script("return await pipeline([1], () => agent('p'))")) + const result = await run(ctx, parent, scripted("return await pipeline([1], () => agent('p'))")) expect(result.stopReason).toBe('error') expect(result.error).toContain('agent() could not start a child') }) @@ -200,7 +200,7 @@ describe('dsh-workflow-workerthread', () => { } ctx.subagents.registerProvider(provider) await ctx.plugin(WorkerWorkflowEngine, { provider: 'rejecting', maxConcurrentAgents: 2 }) - const result = await run(ctx, fakeParent(), script(` + const result = await run(ctx, fakeParent(), scripted(` try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, code: e.code, fatal: e.fatal, message: e.message } } `)) expect(result.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true }) @@ -223,7 +223,7 @@ describe('dsh-workflow-workerthread', () => { } ctx.subagents.registerProvider(provider) await ctx.plugin(WorkerWorkflowEngine, { provider: 'bad-dispose', maxConcurrentAgents: 2 }) - const result = await run(ctx, fakeParent(), script("return await agent('p')")) + const result = await run(ctx, fakeParent(), scripted("return await agent('p')")) expect(result.stopReason).toBe('completed') expect(result.value).toBe('fine') }) @@ -248,17 +248,22 @@ describe('dsh-workflow-workerthread', () => { } ctx.subagents.registerProvider(provider) await ctx.plugin(WorkerWorkflowEngine, { provider: 'coercion-trap-dispose', maxConcurrentAgents: 2 }) - const result = await run(ctx, fakeParent(), script("return await agent('p')")) + const result = await run(ctx, fakeParent(), scripted("return await agent('p')")) expect(result.stopReason).toBe('completed') expect(result.value).toBe('fine') }) }) describe('lifecycle: parse errors, cancellation, termination, disposal', () => { - it('start() throws synchronously for an unparseable script or invalid meta (host-side pre-parse)', async () => { + it('start() throws synchronously for invalid meta data or an unparseable body (host-side pre-checks)', async () => { const { ctx, parent } = await setup() - expect(() => ctx.workflows.start({ script: 'const x = 1', parent })).toThrow(/must begin with/) - expect(() => ctx.workflows.start({ script: script('return ((('), parent })).toThrow(/does not parse/) + // Meta is DATA — shape violations reject loud, every one named. + expect(() => ctx.workflows.start({ script: 'return 1', meta: { name: '', description: 'd' }, parent })).toThrow(/meta\.name must be a non-empty string/) + expect(() => ctx.workflows.start({ script: 'return 1', meta: { name: 'x', description: 'd', extra: 1 } as unknown as WorkflowMeta, parent })).toThrow(/META_INVALID|not a recognized field/) + expect(() => ctx.workflows.start({ ...scripted('return ((('), parent })).toThrow(/does not parse/) + // The likeliest authoring slip — a Claude Code-style meta header in the + // body — gets a pointed message, not a bare SyntaxError. + expect(() => ctx.workflows.start({ ...scripted("export const meta = { name: 'x', description: 'd' }\nreturn 1"), parent })).toThrow(/meta rides the `meta` request field/) }) it('cancel() aborts in-flight children (signal AND cancel RPC) and settles the run cancelled', async () => { @@ -267,7 +272,7 @@ describe('dsh-workflow-workerthread', () => { ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) }) const runEnds: WorkflowResultInfo[] = [] ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) - const handle = ctx.workflows.start({ script: script("return await agent('long job')"), parent }) + const handle = ctx.workflows.start({ ...scripted("return await agent('long job')"), parent }) await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) handle.cancel('user stopped it') const result = await handle.result @@ -287,7 +292,7 @@ describe('dsh-workflow-workerthread', () => { controller.abort() const logs: string[] = [] ctx.on('workflow/log', (_info, message) => { logs.push(message) }) - const handle = ctx.workflows.start({ script: script("log('ran')\nreturn 123"), parent, signal: controller.signal }) + const handle = ctx.workflows.start({ ...scripted("log('ran')\nreturn 123"), parent, signal: controller.signal }) const result = await handle.result expect(result.stopReason).toBe('cancelled') expect(result.value).toBeNull() @@ -298,7 +303,7 @@ describe('dsh-workflow-workerthread', () => { it('cancel() right after start() cancels before the body runs; the signal aborting mid-run cancels like cancel()', async () => { const { ctx, parent, provider } = await setup({ manual: true }) - const first = ctx.workflows.start({ script: script("return await agent('never')"), parent }) + const first = ctx.workflows.start({ ...scripted("return await agent('never')"), parent }) // No-reason cancel: the canonical default reason must ride the result. first.cancel() const firstResult = await first.result @@ -308,7 +313,7 @@ describe('dsh-workflow-workerthread', () => { await first.dispose() const controller = new AbortController() - const second = ctx.workflows.start({ script: script("return await agent('job')"), parent, signal: controller.signal }) + const second = ctx.workflows.start({ ...scripted("return await agent('job')"), parent, signal: controller.signal }) await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) controller.abort() expect((await second.result).stopReason).toBe('cancelled') @@ -323,7 +328,7 @@ describe('dsh-workflow-workerthread', () => { // timing can hit reliably. (The closure runs only after `handle` below // is initialized — the listener fires on the worker's first message.) ctx.on('workflow/log', () => { handle.cancel('cancelled from the log listener') }) - const handle = ctx.workflows.start({ script: script("log('mark')\nreturn await agent('late')"), parent }) + const handle = ctx.workflows.start({ ...scripted("log('mark')\nreturn await agent('late')"), parent }) const result = await handle.result expect(result.stopReason).toBe('cancelled') expect(provider.runs.length).toBe(0) @@ -342,7 +347,7 @@ describe('dsh-workflow-workerthread', () => { // host cancellation. The trailing narration exercises host-side // suppression: posted pre-cancel-processing worker-side, arriving // post-cancel host-side. - script: script(` + ...scripted(` log('started') const end = Date.now() + 1000 while (Date.now() < end) {} @@ -366,7 +371,7 @@ describe('dsh-workflow-workerthread', () => { const runEnds: WorkflowResultInfo[] = [] ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) const handle = ctx.workflows.start({ - script: script("await new Promise(() => {})\nreturn 'unreachable'"), + ...scripted("await new Promise(() => {})\nreturn 'unreachable'"), parent, }) handle.cancel('user aborted') @@ -382,7 +387,7 @@ describe('dsh-workflow-workerthread', () => { it('dispose() on a stuck script returns within the grace instead of hanging (result settles cancelled)', async () => { const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 50 } }) const handle = ctx.workflows.start({ - script: script("await new Promise(() => {})\nreturn 'unreachable'"), + ...scripted("await new Promise(() => {})\nreturn 'unreachable'"), parent, }) const before = Date.now() @@ -394,7 +399,7 @@ describe('dsh-workflow-workerthread', () => { it('dispose() is idempotent and settles cleanly after a completed run', async () => { const { ctx, parent } = await setup() - const handle = ctx.workflows.start({ script: script('return 1'), parent }) + const handle = ctx.workflows.start({ ...scripted('return 1'), parent }) await handle.result await handle.dispose() await handle.dispose() @@ -405,7 +410,7 @@ describe('dsh-workflow-workerthread', () => { // apart from every other timeout in flight. const GRACE = 44_444 const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: GRACE } }) - const handle = ctx.workflows.start({ script: script('return 1'), parent }) + const handle = ctx.workflows.start({ ...scripted('return 1'), parent }) await handle.result const spy = vi.spyOn(globalThis, 'setTimeout') try { @@ -424,7 +429,7 @@ describe('dsh-workflow-workerthread', () => { it('strays: children fired without await are aborted once the script settles, and dispose() waits for their disposal', async () => { const { ctx, parent, provider } = await setup({ manual: true, disposeDelayMs: 40 }) const handle = ctx.workflows.start({ - script: script(` + ...scripted(` agent('stray') return 'done without awaiting' `), @@ -468,7 +473,7 @@ describe('dsh-workflow-workerthread', () => { ctx.subagents.registerProvider(provider) await ctx.plugin(WorkerWorkflowEngine, { provider: 'signal-only', maxConcurrentAgents: 2 }) const handle = ctx.workflows.start({ - script: script(` + ...scripted(` agent('stray, never awaited') return 'done' `), @@ -515,7 +520,7 @@ describe('dsh-workflow-workerthread', () => { // microtask yields let the agent() continuation POST its child-start // before the spin seizes the worker's loop (the posted message needs // no further worker-loop turns to reach the host). - script: script(` + ...scripted(` agent('wedged child') for (let i = 0; i < 20; i++) await null const end = Date.now() + 1500 @@ -560,7 +565,7 @@ describe('dsh-workflow-workerthread', () => { // The stray child's start RPC reaches the host, then the script kills // its own worker through the documented vm escape — the host must // settle `error` with the exit diagnostics and wind the child down. - script: script(` + ...scripted(` agent('doomed') const proc = ${ESCAPE} const st = globalThis.constructor.constructor('return setTimeout')() @@ -583,7 +588,7 @@ describe('dsh-workflow-workerthread', () => { it('an uncaught exception inside the worker surfaces as an error result and reaps the in-flight child', async () => { const { ctx, parent, provider } = await setup({ manual: true }) const handle = ctx.workflows.start({ - script: script(` + ...scripted(` agent('in flight when the worker dies') const proc = ${ESCAPE} const st = globalThis.constructor.constructor('return setTimeout')() @@ -613,7 +618,7 @@ describe('dsh-workflow-workerthread', () => { // The STRAY child settles instantly, so its wrapper starts the slow // host-side disposal concurrently while the script goes on to kill // its own worker — the ack then resolves into a dead thread. - script: script(` + ...scripted(` agent('stray, never awaited') const proc = ${ESCAPE} const st = globalThis.constructor.constructor('return setTimeout')() @@ -632,7 +637,7 @@ describe('dsh-workflow-workerthread', () => { it('a worker death AFTER a cancel reports cancelled, not error', async () => { const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 60_000 } }) const handle = ctx.workflows.start({ - script: script(` + ...scripted(` const proc = ${ESCAPE} const st = globalThis.constructor.constructor('return setTimeout')() log('armed') @@ -659,8 +664,8 @@ describe('dsh-workflow-workerthread', () => { const { ctx, parent } = await setup() let eventMeta: WorkflowRunInfo | undefined ctx.on('workflow/start', (info) => { eventMeta = info }) - const first = ctx.workflows.start({ script: script('return 1'), parent }) - const second = ctx.workflows.start({ script: script('return 2'), parent }) + const first = ctx.workflows.start({ ...scripted('return 1'), parent }) + const second = ctx.workflows.start({ ...scripted('return 2'), parent }) expect(first.id).not.toBe(second.id) eventMeta!.meta.name = 'corrupted' expect(second.meta.name).toBe('test-flow') @@ -676,7 +681,7 @@ describe('dsh-workflow-workerthread', () => { expect(ctx.get('workflows')).toBeDefined() // A zero-agent run through the DEFAULT config exercises the auto // concurrency resolution (cores - 2, capped) in start(). - const result = await run(ctx, fakeParent(), script('return 6 * 7')) + const result = await run(ctx, fakeParent(), scripted('return 6 * 7')) expect(result.value).toBe(42) await fiber.dispose() expect(ctx.get('workflows')).toBeUndefined() diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md index 317aaf9f81..5ff8028b0d 100644 --- a/packages/workflow/workflow/README.md +++ b/packages/workflow/workflow/README.md @@ -11,7 +11,7 @@ The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with ## Vocabulary - `WorkflowStartRequest` — `{ script, args?, parent: Agent, signal? }`. `parent` is REQUIRED: every child the script spawns is attributed to it. `args` must be plain host-realm JSON data. -- `WorkflowMeta` / `WorkflowPhase` — the script's validated `export const meta` block (Claude Code format: required `name`/`description`, optional `whenToUse`/`phases`). +- `WorkflowMeta` / `WorkflowPhase` — the workflow's identity block, carried as plain JSON data on the start request (Claude Code meta vocabulary: required `name`/`description`, optional `whenToUse`/`phases`) and shape-validated by the engine. - `WorkflowRun` — `{ id, meta, result, cancel(reason?), dispose() }`; the consumer awaits `result` and MUST `dispose` on every path. - `WorkflowResult` — `{ value, stopReason: 'completed'|'cancelled'|'error', error?, agentsStarted }`; `value` is the script's materialized return (plain JSON data; `null` for no return). - `WorkflowError` — `HarnessError` with a `WorkflowErrorCode` and a `fatal` flag driving the combinator discipline: a fatal error (bad hook arguments, unsupported options/schemas, tripped caps, seam start failures, cancellation) always propagates through `parallel()`/`pipeline()` instead of dissolving into a per-item `null`. `isFatalWorkflowError(error)` is the catch-site predicate. diff --git a/packages/workflow/workflow/src/types.ts b/packages/workflow/workflow/src/types.ts index 8552e32454..66da4f1268 100644 --- a/packages/workflow/workflow/src/types.ts +++ b/packages/workflow/workflow/src/types.ts @@ -35,9 +35,11 @@ export interface WorkflowPhase { } /** - * The script's `export const meta` block, validated by the engine before the - * body runs. `name`/`description` are required; the rest is optional - * annotation. Matches the Claude Code dynamic-workflows script format. + * The script's identity block, provided as plain JSON data alongside the + * script body (the model-facing tool carries it as its `meta` parameter) and + * validated by the engine before the body runs. `name`/`description` are + * required; the rest is optional annotation. The field vocabulary matches the + * Claude Code dynamic-workflows meta block. */ export interface WorkflowMeta { /** Short kebab-case workflow name (display + persistence key). */ @@ -51,14 +53,18 @@ export interface WorkflowMeta { } /** - * What a caller asks for when starting a workflow run. `parent` is REQUIRED — - * every `agent()` the script spawns is attributed to it (cwd, lineage, depth - * flow through the subagent seam). `args` must be plain host-realm JSON data; - * the engine exposes it to the script as the `args` global. + * What a caller asks for when starting a workflow run. `meta` and `args` are + * plain JSON DATA by the seam contract (the tool builds both from the model's + * schema-validated call; the engine validates `meta`'s shape and rejects loud + * before anything runs) — an engine never evaluates script text to obtain + * them. `parent` is REQUIRED — every `agent()` the script spawns is + * attributed to it (cwd, lineage, depth flow through the subagent seam). */ export interface WorkflowStartRequest { - /** The full script text: `export const meta = {...}` + a plain-JS body. */ + /** The plain-JS script body (top-level await allowed; ends with `return `). */ script: string + /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */ + meta: WorkflowMeta /** Optional input exposed verbatim to the script as the `args` global. */ args?: unknown /** The agent on whose behalf the run executes (parent of every child). */ From f91bfc1fcfadb370a38bc1a3463cd7ee23df5276 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 20:25:59 +0800 Subject: [PATCH 102/119] test: re-record the header pin and workflow-run for the meta-parameter schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The workflow tool's wire schema changed (required meta object parameter; body-only script). Request-header content is pinned by exactly ONE scenario (text-turn) and scrubbed to {{system}}/{{tools}} tokens everywhere else, so the schema change re-records exactly two fixtures: - text-turn — the pinned header itself (the one committed copy of the tool schemas; every other scenario's live header is asserted equal to this pin by the uniformity guard). - workflow-run — its recorded interaction used the removed call shape (meta embedded in the script), which the engine now rejects; the authored prompt is updated to dictate the new shape (meta as a parameter, body-only script) and the scenario re-recorded to a clean single call. Every other fixture stays byte-identical and replays green against the new pin. Known pre-existing exception: fs-policy-reject's recording carries a GNU-only sed -i fallback that fails BSD/macOS replay — kept out of this change deliberately (the snapshot CI lane is ubuntu). --- .../tests/snapshots/text-turn/session.jsonl | 69 ++-- .../snapshots/text-turn/stdout.golden.jsonl | 9 +- .../tests/snapshots/workflow-run/input.json | 2 +- .../snapshots/workflow-run/session.1.jsonl | 75 ++-- .../snapshots/workflow-run/session.jsonl | 359 ++++++++++-------- .../workflow-run/stdout.golden.jsonl | 100 +++-- 6 files changed, 366 insertions(+), 248 deletions(-) diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl index 39898c5003..8475c97896 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl @@ -1,33 +1,36 @@ -{"type":"session","version":0,"id":"423e2c78-075e-4286-8027-85b0e64da45d","createdAt":1783437535685,"cwd":"/tmp/acp-snap-cwd-XUOYdd"} -{"type":"turn/start","seq":0,"time":1783437535688,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783437535689,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783437535690,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783437535690,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-XUOYdd.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe script MUST begin with `export const meta = {...}` — a PURE object literal (no variables, calls, or template interpolation) with required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The body after it is plain JavaScript (NOT TypeScript) running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The complete workflow script: `export const meta = {...}` followed by the plain-JS body (top-level await allowed; end with `return `)."},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783437536390,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783437536390,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783437536568,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783437536591,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":11,"time":1783437536592,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":12,"time":1783437536615,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":13,"time":1783437536616,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":14,"time":1783437536647,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"P"}}} -{"type":"assistant/chunk","seq":15,"time":1783437536648,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONG"}}} -{"type":"assistant/chunk","seq":16,"time":1783437536648,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\""}}} -{"type":"assistant/chunk","seq":17,"time":1783437536674,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":18,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" no"}}} -{"type":"assistant/chunk","seq":19,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} -{"type":"assistant/chunk","seq":20,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":21,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":22,"time":1783437536675,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"P"}}} -{"type":"assistant/chunk","seq":23,"time":1783437536702,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONG"}}} -{"type":"assistant/chunk","seq":24,"time":1783437536703,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"."}}} -{"type":"assistant/chunk","seq":25,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"PONG.\" and no tools."}}}} -{"type":"assistant/chunk","seq":26,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PONG."}}}} -{"type":"assistant/chunk","seq":27,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2867,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":16}}}} -{"type":"assistant/chunk","seq":28,"time":1783437536704,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":29,"time":1783437536706,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"PONG.\" and no tools."},{"type":"text","text":"PONG."}],"usage":{"inputTokens":2867,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":16}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28],"surfaceOp":"append"} -{"type":"step/end","seq":30,"time":1783437536706,"data":{"turn":1,"step":1}} -{"type":"turn/end","seq":31,"time":1783437536706,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"539aa64c-7f37-40ff-abd8-ed45b717be1b","createdAt":1783600629539,"cwd":"/var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-ka5r8w"} +{"type":"turn/start","seq":0,"time":1783600629541,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783600629541,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783600629542,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783600629542,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-ka5r8w.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783600630819,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783600630820,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783600630822,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783600630852,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783600630852,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783600630852,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783600630852,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":11,"time":1783600630885,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":12,"time":1783600630886,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":13,"time":1783600630926,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":14,"time":1783600630926,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} +{"type":"assistant/chunk","seq":15,"time":1783600630926,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":16,"time":1783600630926,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"P"}}} +{"type":"assistant/chunk","seq":17,"time":1783600630926,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONG"}}} +{"type":"assistant/chunk","seq":18,"time":1783600630926,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":19,"time":1783600630944,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":20,"time":1783600630944,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" not"}}} +{"type":"assistant/chunk","seq":21,"time":1783600630980,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}} +{"type":"assistant/chunk","seq":22,"time":1783600630980,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" any"}}} +{"type":"assistant/chunk","seq":23,"time":1783600630980,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} +{"type":"assistant/chunk","seq":24,"time":1783600630980,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":25,"time":1783600630980,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":26,"time":1783600630980,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"P"}}} +{"type":"assistant/chunk","seq":27,"time":1783600631006,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONG"}}} +{"type":"assistant/chunk","seq":28,"time":1783600631008,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."}}}} +{"type":"assistant/chunk","seq":29,"time":1783600631009,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PONG"}}}} +{"type":"assistant/chunk","seq":30,"time":1783600631009,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3091,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}}}} +{"type":"assistant/chunk","seq":31,"time":1783600631009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":32,"time":1783600631011,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."},{"type":"text","text":"PONG"}],"usage":{"inputTokens":3091,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"surfaceOp":"append"} +{"type":"step/end","seq":33,"time":1783600631011,"data":{"turn":1,"step":1}} +{"type":"turn/end","seq":34,"time":1783600631011,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl index bc3582f027..dda3afb9c5 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/text-turn/stdout.golden.jsonl @@ -8,15 +8,18 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"P"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONG"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" no"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" not"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" use"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" any"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"P"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONG"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/workflow-run/input.json b/examples/acp-agent/tests/snapshots/workflow-run/input.json index 2c402dc49e..e5deb7edd0 100644 --- a/examples/acp-agent/tests/snapshots/workflow-run/input.json +++ b/examples/acp-agent/tests/snapshots/workflow-run/input.json @@ -2,6 +2,6 @@ "steps": [ { "op": "initialize" }, { "op": "newSession" }, - { "op": "prompt", "text": "Use the workflow tool exactly once, with args omitted and this EXACT script (copy it verbatim):\nexport const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool." } + { "op": "prompt", "text": "Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim):\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool." } ] } diff --git a/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl index 34f6710ee1..a8c1d6018b 100644 --- a/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl +++ b/examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl @@ -1,39 +1,36 @@ -{"type":"session","version":0,"id":"ba8789c0-cfec-4ec0-9f19-d30e086c3428","createdAt":1783352155100,"cwd":"/tmp/acp-snap-cwd-Z6uc79","parentSession":"322d3a3d-add3-4926-a507-9a6a70a2123a"} -{"type":"turn/start","seq":0,"time":1783352155101,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783352155101,"data":{"content":[{"type":"text","text":"Reply with exactly the word WF_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783352155102,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783352155102,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783352156006,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783352156006,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783352156119,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783352156148,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} -{"type":"assistant/chunk","seq":8,"time":1783352156148,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" asking"}}} -{"type":"assistant/chunk","seq":9,"time":1783352156148,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":10,"time":1783352156148,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":11,"time":1783352156148,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":12,"time":1783352156176,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":13,"time":1783352156176,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":14,"time":1783352156176,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":15,"time":1783352156205,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} -{"type":"assistant/chunk","seq":16,"time":1783352156205,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":17,"time":1783352156205,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}} -{"type":"assistant/chunk","seq":18,"time":1783352156205,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}} -{"type":"assistant/chunk","seq":19,"time":1783352156205,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}} -{"type":"assistant/chunk","seq":20,"time":1783352156205,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":21,"time":1783352156234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} -{"type":"assistant/chunk","seq":22,"time":1783352156234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":23,"time":1783352156234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" nothing"}}} -{"type":"assistant/chunk","seq":24,"time":1783352156234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" else"}}} -{"type":"assistant/chunk","seq":25,"time":1783352156234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":26,"time":1783352156263,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":27,"time":1783352156263,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"WF"}}} -{"type":"assistant/chunk","seq":28,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_CH"}}} -{"type":"assistant/chunk","seq":29,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ILD"}}} -{"type":"assistant/chunk","seq":30,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} -{"type":"assistant/chunk","seq":31,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user is asking me to reply with exactly the word \"WF_CHILD_OK\" and nothing else."}}}} -{"type":"assistant/chunk","seq":32,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WF_CHILD_OK"}}}} -{"type":"assistant/chunk","seq":33,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2865,"outputTokens":26,"cacheReadTokens":0,"reasoningTokens":21}}}} -{"type":"assistant/chunk","seq":34,"time":1783352156264,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":35,"time":1783352156264,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user is asking me to reply with exactly the word \"WF_CHILD_OK\" and nothing else."},{"type":"text","text":"WF_CHILD_OK"}],"usage":{"inputTokens":2865,"outputTokens":26,"cacheReadTokens":0,"reasoningTokens":21}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34],"surfaceOp":"append"} -{"type":"step/end","seq":36,"time":1783352156265,"data":{"turn":1,"step":1}} -{"type":"turn/end","seq":37,"time":1783352156265,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"583a4db2-3350-436c-b4a5-5615fd159052","createdAt":1783600636316,"cwd":"/var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-vdJYjz","parentSession":"3fd7d599-56b1-493a-930d-f1fc5e1556e8"} +{"type":"turn/start","seq":0,"time":1783600636316,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783600636316,"data":{"content":[{"type":"text","text":"Reply with exactly the word WF_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783600636316,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783600636317,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783600638073,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783600638073,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783600638173,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":11,"time":1783600638189,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":12,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":13,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":14,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}} +{"type":"assistant/chunk","seq":15,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}} +{"type":"assistant/chunk","seq":16,"time":1783600638213,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}} +{"type":"assistant/chunk","seq":17,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":18,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":19,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":20,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" nothing"}}} +{"type":"assistant/chunk","seq":21,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" else"}}} +{"type":"assistant/chunk","seq":22,"time":1783600638242,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":23,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":24,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"WF"}}} +{"type":"assistant/chunk","seq":25,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_CH"}}} +{"type":"assistant/chunk","seq":26,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ILD"}}} +{"type":"assistant/chunk","seq":27,"time":1783600638276,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} +{"type":"assistant/chunk","seq":28,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"WF_CHILD_OK\" and nothing else."}}}} +{"type":"assistant/chunk","seq":29,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WF_CHILD_OK"}}}} +{"type":"assistant/chunk","seq":30,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3072,"reasoningTokens":18}}}} +{"type":"assistant/chunk","seq":31,"time":1783600638280,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":32,"time":1783600638281,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"WF_CHILD_OK\" and nothing else."},{"type":"text","text":"WF_CHILD_OK"}],"usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3072,"reasoningTokens":18}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"surfaceOp":"append"} +{"type":"step/end","seq":33,"time":1783600638281,"data":{"turn":1,"step":1}} +{"type":"turn/end","seq":34,"time":1783600638281,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl index 927e1408bd..ab53f20550 100644 --- a/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl +++ b/examples/acp-agent/tests/snapshots/workflow-run/session.jsonl @@ -1,150 +1,209 @@ -{"type":"session","version":0,"id":"322d3a3d-add3-4926-a507-9a6a70a2123a","createdAt":1783352153441,"cwd":"/tmp/acp-snap-cwd-Z6uc79"} -{"type":"turn/start","seq":0,"time":1783352153445,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783352153446,"data":{"content":[{"type":"text","text":"Use the workflow tool exactly once, with args omitted and this EXACT script (copy it verbatim):\nexport const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783352153447,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783352153447,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783352154106,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783352154106,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783352154306,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783352154335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783352154335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783352154335,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783352154336,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":11,"time":1783352154363,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":12,"time":1783352154363,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exact"}}} -{"type":"assistant/chunk","seq":13,"time":1783352154363,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}} -{"type":"assistant/chunk","seq":14,"time":1783352154363,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" script"}}} -{"type":"assistant/chunk","seq":15,"time":1783352154391,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" provided"}}} -{"type":"assistant/chunk","seq":16,"time":1783352154392,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":17,"time":1783352154392,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}} -{"type":"assistant/chunk","seq":18,"time":1783352154421,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":19,"time":1783352154421,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":20,"time":1783352154421,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":21,"time":1783352154450,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} -{"type":"assistant/chunk","seq":22,"time":1783352154450,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} -{"type":"assistant/chunk","seq":23,"time":1783352154450,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" WORK"}}} -{"type":"assistant/chunk","seq":24,"time":1783352154450,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}} -{"type":"assistant/chunk","seq":25,"time":1783352154451,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}} -{"type":"assistant/chunk","seq":26,"time":1783352154451,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}} -{"type":"assistant/chunk","seq":27,"time":1783352154478,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":28,"time":1783352154478,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":29,"time":1783352154478,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} -{"type":"assistant/chunk","seq":30,"time":1783352154509,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":31,"time":1783352154509,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}} -{"type":"assistant/chunk","seq":32,"time":1783352154509,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}} -{"type":"assistant/chunk","seq":33,"time":1783352154510,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":34,"time":1783352154536,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" as"}}} -{"type":"assistant/chunk","seq":35,"time":1783352154536,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" instructed"}}} -{"type":"assistant/chunk","seq":36,"time":1783352154575,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":37,"time":1783352154626,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":38,"time":1783352154626,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":39,"time":1783352154656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":40,"time":1783352154656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":41,"time":1783352154656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"script"}}} -{"type":"assistant/chunk","seq":42,"time":1783352154683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":43,"time":1783352154683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":44,"time":1783352154683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":45,"time":1783352154683,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"export"}}} -{"type":"assistant/chunk","seq":46,"time":1783352154713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" const"}}} -{"type":"assistant/chunk","seq":47,"time":1783352154713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" meta"}}} -{"type":"assistant/chunk","seq":48,"time":1783352154713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":49,"time":1783352154713,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" {"}}} -{"type":"assistant/chunk","seq":50,"time":1783352154714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" name"}}} -{"type":"assistant/chunk","seq":51,"time":1783352154741,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":52,"time":1783352154741,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" '"}}} -{"type":"assistant/chunk","seq":53,"time":1783352154741,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"sn"}}} -{"type":"assistant/chunk","seq":54,"time":1783352154741,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"apshot"}}} -{"type":"assistant/chunk","seq":55,"time":1783352154741,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"-flow"}}} -{"type":"assistant/chunk","seq":56,"time":1783352154741,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"',"}}} -{"type":"assistant/chunk","seq":57,"time":1783352154773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":58,"time":1783352154773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":59,"time":1783352154773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" '"}}} -{"type":"assistant/chunk","seq":60,"time":1783352154773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"one"}}} -{"type":"assistant/chunk","seq":61,"time":1783352154773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" child"}}} -{"type":"assistant/chunk","seq":62,"time":1783352154798,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" for"}}} -{"type":"assistant/chunk","seq":63,"time":1783352154799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" the"}}} -{"type":"assistant/chunk","seq":64,"time":1783352154799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" snapshot"}}} -{"type":"assistant/chunk","seq":65,"time":1783352154799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"'"}}} -{"type":"assistant/chunk","seq":66,"time":1783352154799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" }\\n"}}} -{"type":"assistant/chunk","seq":67,"time":1783352154799,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"phase"}}} -{"type":"assistant/chunk","seq":68,"time":1783352154827,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"('"}}} -{"type":"assistant/chunk","seq":69,"time":1783352154827,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"Run"}}} -{"type":"assistant/chunk","seq":70,"time":1783352154856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"')\\n"}}} -{"type":"assistant/chunk","seq":71,"time":1783352154856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":72,"time":1783352154856,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" reply"}}} -{"type":"assistant/chunk","seq":73,"time":1783352154884,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":74,"time":1783352154885,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":75,"time":1783352154885,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" agent"}}} -{"type":"assistant/chunk","seq":76,"time":1783352154885,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"('"}}} -{"type":"assistant/chunk","seq":77,"time":1783352154914,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"Reply"}}} -{"type":"assistant/chunk","seq":78,"time":1783352154914,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" with"}}} -{"type":"assistant/chunk","seq":79,"time":1783352154915,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" exactly"}}} -{"type":"assistant/chunk","seq":80,"time":1783352154915,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" the"}}} -{"type":"assistant/chunk","seq":81,"time":1783352154942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" word"}}} -{"type":"assistant/chunk","seq":82,"time":1783352154942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" WF"}}} -{"type":"assistant/chunk","seq":83,"time":1783352154943,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"_CH"}}} -{"type":"assistant/chunk","seq":84,"time":1783352154943,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"ILD"}}} -{"type":"assistant/chunk","seq":85,"time":1783352154971,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":86,"time":1783352154971,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" and"}}} -{"type":"assistant/chunk","seq":87,"time":1783352154971,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" nothing"}}} -{"type":"assistant/chunk","seq":88,"time":1783352154972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" else"}}} -{"type":"assistant/chunk","seq":89,"time":1783352154972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":".')\\n"}}} -{"type":"assistant/chunk","seq":90,"time":1783352154972,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":91,"time":1783352155000,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" {"}}} -{"type":"assistant/chunk","seq":92,"time":1783352155000,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" reply"}}} -{"type":"assistant/chunk","seq":93,"time":1783352155000,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":" }"}}} -{"type":"assistant/chunk","seq":94,"time":1783352155001,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":95,"time":1783352155029,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":96,"time":1783352155091,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run the exact workflow script provided and then reply with the single word WORKFLOW_DONE. Let me do this exactly as instructed."}}}} -{"type":"assistant/chunk","seq":97,"time":1783352155092,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","arguments":"{\"script\": \"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\"}"}}}} -{"type":"assistant/chunk","seq":98,"time":1783352155092,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2947,"outputTokens":124,"cacheReadTokens":0,"reasoningTokens":32}}}} -{"type":"assistant/chunk","seq":99,"time":1783352155092,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":100,"time":1783352155094,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run the exact workflow script provided and then reply with the single word WORKFLOW_DONE. Let me do this exactly as instructed."},{"type":"tool-call","id":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","arguments":"{\"script\": \"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\"}"}],"usage":{"inputTokens":2947,"outputTokens":124,"cacheReadTokens":0,"reasoningTokens":32}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99],"surfaceOp":"append"} -{"type":"tool/call","seq":101,"time":1783352155094,"data":{"turn":1,"step":1,"callId":"call_00_Vp9f0l50KeeHRfcBezz08251","name":"workflow","arguments":"{\"script\": \"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\"}"}} -{"type":"tool/result","seq":102,"time":1783352156271,"data":{"turn":1,"step":1,"callId":"call_00_Vp9f0l50KeeHRfcBezz08251","content":[{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WF_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[101],"surfaceOp":"append"} -{"type":"step/end","seq":103,"time":1783352156271,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":104,"time":1783352156272,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":105,"time":1783352156660,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":106,"time":1783352156660,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":107,"time":1783352156787,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}} -{"type":"assistant/chunk","seq":108,"time":1783352156823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" returned"}}} -{"type":"assistant/chunk","seq":109,"time":1783352156842,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}} -{"type":"assistant/chunk","seq":110,"time":1783352156842,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":111,"time":1783352156870,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":112,"time":1783352156871,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":113,"time":1783352156899,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":114,"time":1783352156899,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}} -{"type":"assistant/chunk","seq":115,"time":1783352156900,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}} -{"type":"assistant/chunk","seq":116,"time":1783352156900,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}} -{"type":"assistant/chunk","seq":117,"time":1783352156900,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":118,"time":1783352156900,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} -{"type":"assistant/chunk","seq":119,"time":1783352156927,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Now"}}} -{"type":"assistant/chunk","seq":120,"time":1783352156928,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} -{"type":"assistant/chunk","seq":121,"time":1783352156928,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} -{"type":"assistant/chunk","seq":122,"time":1783352156928,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":123,"time":1783352156928,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":124,"time":1783352156956,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":125,"time":1783352156956,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":126,"time":1783352156956,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} -{"type":"assistant/chunk","seq":127,"time":1783352156956,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}} -{"type":"assistant/chunk","seq":128,"time":1783352156956,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" WORK"}}} -{"type":"assistant/chunk","seq":129,"time":1783352156985,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}} -{"type":"assistant/chunk","seq":130,"time":1783352156985,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}} -{"type":"assistant/chunk","seq":131,"time":1783352156985,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}} -{"type":"assistant/chunk","seq":132,"time":1783352156985,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":133,"time":1783352156986,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" as"}}} -{"type":"assistant/chunk","seq":134,"time":1783352156986,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" instructed"}}} -{"type":"assistant/chunk","seq":135,"time":1783352157015,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":136,"time":1783352157016,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":137,"time":1783352157016,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WORK"}}} -{"type":"assistant/chunk","seq":138,"time":1783352157016,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"FL"}}} -{"type":"assistant/chunk","seq":139,"time":1783352157016,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OW"}}} -{"type":"assistant/chunk","seq":140,"time":1783352157016,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_D"}}} -{"type":"assistant/chunk","seq":141,"time":1783352157044,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} -{"type":"assistant/chunk","seq":142,"time":1783352157044,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with the single word WORKFLOW_DONE as instructed."}}}} -{"type":"assistant/chunk","seq":143,"time":1783352157045,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WORKFLOW_DONE"}}}} -{"type":"assistant/chunk","seq":144,"time":1783352157045,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":165,"outputTokens":36,"cacheReadTokens":2944,"reasoningTokens":30}}}} -{"type":"assistant/chunk","seq":145,"time":1783352157045,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":146,"time":1783352157045,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with the single word WORKFLOW_DONE as instructed."},{"type":"text","text":"WORKFLOW_DONE"}],"usage":{"inputTokens":165,"outputTokens":36,"cacheReadTokens":2944,"reasoningTokens":30}},"sourceEventSeqs":[105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145],"surfaceOp":"append"} -{"type":"step/end","seq":147,"time":1783352157045,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":148,"time":1783352157045,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"3fd7d599-56b1-493a-930d-f1fc5e1556e8","createdAt":1783600631835,"cwd":"/var/folders/bn/vj1dvck95yd5jh3x4wskflxm0000gn/T/acp-snap-cwd-vdJYjz"} +{"type":"turn/start","seq":0,"time":1783600631838,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783600631838,"data":{"content":[{"type":"text","text":"Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim):\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\nAfter the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783600631839,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783600631839,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783600634643,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783600634643,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}} +{"type":"assistant/chunk","seq":11,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":12,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}} +{"type":"assistant/chunk","seq":13,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} +{"type":"assistant/chunk","seq":14,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":15,"time":1783600635634,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" once"}}} +{"type":"assistant/chunk","seq":16,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":17,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" specific"}}} +{"type":"assistant/chunk","seq":18,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" parameters"}}} +{"type":"assistant/chunk","seq":19,"time":1783600635635,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":20,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":21,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":22,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" carefully"}}} +{"type":"assistant/chunk","seq":23,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" follow"}}} +{"type":"assistant/chunk","seq":24,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":25,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" instructions"}}} +{"type":"assistant/chunk","seq":26,"time":1783600635743,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n\n"}}} +{"type":"assistant/chunk","seq":27,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}} +{"type":"assistant/chunk","seq":28,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":29,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" args"}}} +{"type":"assistant/chunk","seq":30,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" omitted"}}} +{"type":"assistant/chunk","seq":31,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ("}}} +{"type":"assistant/chunk","seq":32,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"so"}}} +{"type":"assistant/chunk","seq":33,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":34,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" don"}}} +{"type":"assistant/chunk","seq":35,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"'t"}}} +{"type":"assistant/chunk","seq":36,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" include"}}} +{"type":"assistant/chunk","seq":37,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}} +{"type":"assistant/chunk","seq":38,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":")\n"}}} +{"type":"assistant/chunk","seq":39,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}} +{"type":"assistant/chunk","seq":40,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":41,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" meta"}}} +{"type":"assistant/chunk","seq":42,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ="}}} +{"type":"assistant/chunk","seq":43,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" {"}}} +{"type":"assistant/chunk","seq":44,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":45,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"name"}}} +{"type":"assistant/chunk","seq":46,"time":1783600635744,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\":"}}} +{"type":"assistant/chunk","seq":47,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":48,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"sn"}}} +{"type":"assistant/chunk","seq":49,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"apshot"}}} +{"type":"assistant/chunk","seq":50,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"-flow"}}} +{"type":"assistant/chunk","seq":51,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\","}}} +{"type":"assistant/chunk","seq":52,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":53,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"description"}}} +{"type":"assistant/chunk","seq":54,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\":"}}} +{"type":"assistant/chunk","seq":55,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":56,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"one"}}} +{"type":"assistant/chunk","seq":57,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" child"}}} +{"type":"assistant/chunk","seq":58,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" for"}}} +{"type":"assistant/chunk","seq":59,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":60,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" snapshot"}}} +{"type":"assistant/chunk","seq":61,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":62,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" }\n"}}} +{"type":"assistant/chunk","seq":63,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}} +{"type":"assistant/chunk","seq":64,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":65,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" script"}}} +{"type":"assistant/chunk","seq":66,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" ="}}} +{"type":"assistant/chunk","seq":67,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" as"}}} +{"type":"assistant/chunk","seq":68,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" given"}}} +{"type":"assistant/chunk","seq":69,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" verb"}}} +{"type":"assistant/chunk","seq":70,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"atim"}}} +{"type":"assistant/chunk","seq":71,"time":1783600635745,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}} +{"type":"assistant/chunk","seq":72,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"4"}}} +{"type":"assistant/chunk","seq":73,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":74,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" After"}}} +{"type":"assistant/chunk","seq":75,"time":1783600635746,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" it"}}} +{"type":"assistant/chunk","seq":76,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} +{"type":"assistant/chunk","seq":77,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":","}}} +{"type":"assistant/chunk","seq":78,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":79,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":80,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":81,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WORK"}}} +{"type":"assistant/chunk","seq":82,"time":1783600635754,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}} +{"type":"assistant/chunk","seq":83,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}} +{"type":"assistant/chunk","seq":84,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}} +{"type":"assistant/chunk","seq":85,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":86,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\"\n\n"}}} +{"type":"assistant/chunk","seq":87,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} +{"type":"assistant/chunk","seq":88,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":89,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}} +{"type":"assistant/chunk","seq":90,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":91,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":92,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":93,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":94,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":95,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":96,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":97,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"meta"}}} +{"type":"assistant/chunk","seq":98,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":99,"time":1783600635756,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":100,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"{\""}}} +{"type":"assistant/chunk","seq":101,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"name"}}} +{"type":"assistant/chunk","seq":102,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\":"}}} +{"type":"assistant/chunk","seq":103,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" \""}}} +{"type":"assistant/chunk","seq":104,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"sn"}}} +{"type":"assistant/chunk","seq":105,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"apshot"}}} +{"type":"assistant/chunk","seq":106,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"-flow"}}} +{"type":"assistant/chunk","seq":107,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\","}}} +{"type":"assistant/chunk","seq":108,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" \""}}} +{"type":"assistant/chunk","seq":109,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"description"}}} +{"type":"assistant/chunk","seq":110,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\":"}}} +{"type":"assistant/chunk","seq":111,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" \""}}} +{"type":"assistant/chunk","seq":112,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"one"}}} +{"type":"assistant/chunk","seq":113,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" child"}}} +{"type":"assistant/chunk","seq":114,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" for"}}} +{"type":"assistant/chunk","seq":115,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" the"}}} +{"type":"assistant/chunk","seq":116,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" snapshot"}}} +{"type":"assistant/chunk","seq":117,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":118,"time":1783600635757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":119,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":", "}}} +{"type":"assistant/chunk","seq":120,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":121,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"script"}}} +{"type":"assistant/chunk","seq":122,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":123,"time":1783600635759,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":124,"time":1783600635764,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":125,"time":1783600635764,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\\n"}}} +{"type":"assistant/chunk","seq":126,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"phase"}}} +{"type":"assistant/chunk","seq":127,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"('"}}} +{"type":"assistant/chunk","seq":128,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"Run"}}} +{"type":"assistant/chunk","seq":129,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"')\\n"}}} +{"type":"assistant/chunk","seq":130,"time":1783600636039,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":131,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" reply"}}} +{"type":"assistant/chunk","seq":132,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":133,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":134,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" agent"}}} +{"type":"assistant/chunk","seq":135,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"('"}}} +{"type":"assistant/chunk","seq":136,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"Reply"}}} +{"type":"assistant/chunk","seq":137,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" with"}}} +{"type":"assistant/chunk","seq":138,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" exactly"}}} +{"type":"assistant/chunk","seq":139,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" the"}}} +{"type":"assistant/chunk","seq":140,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" word"}}} +{"type":"assistant/chunk","seq":141,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" WF"}}} +{"type":"assistant/chunk","seq":142,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"_CH"}}} +{"type":"assistant/chunk","seq":143,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"ILD"}}} +{"type":"assistant/chunk","seq":144,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":145,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" and"}}} +{"type":"assistant/chunk","seq":146,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" nothing"}}} +{"type":"assistant/chunk","seq":147,"time":1783600636245,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" else"}}} +{"type":"assistant/chunk","seq":148,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":".')\\n"}}} +{"type":"assistant/chunk","seq":149,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":150,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" {"}}} +{"type":"assistant/chunk","seq":151,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" reply"}}} +{"type":"assistant/chunk","seq":152,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":" }\\n"}}} +{"type":"assistant/chunk","seq":153,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":154,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":155,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully follow the instructions:\n\n1. args omitted (so I don't include it)\n2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }\n3. script = as given verbatim\n4. After it returns, reply with \"WORKFLOW_DONE\"\n\nLet me do exactly that."}}}} +{"type":"assistant/chunk","seq":156,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","arguments":"{\"meta\": {\"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\"}, \"script\": \"\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\\n\"}"}}}} +{"type":"assistant/chunk","seq":157,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3174,"outputTokens":191,"cacheReadTokens":0,"reasoningTokens":88}}}} +{"type":"assistant/chunk","seq":158,"time":1783600636246,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":159,"time":1783600636247,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully follow the instructions:\n\n1. args omitted (so I don't include it)\n2. meta = { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }\n3. script = as given verbatim\n4. After it returns, reply with \"WORKFLOW_DONE\"\n\nLet me do exactly that."},{"type":"tool-call","id":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","arguments":"{\"meta\": {\"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\"}, \"script\": \"\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\\n\"}"}],"usage":{"inputTokens":3174,"outputTokens":191,"cacheReadTokens":0,"reasoningTokens":88}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158],"surfaceOp":"append"} +{"type":"tool/call","seq":160,"time":1783600636247,"data":{"turn":1,"step":1,"callId":"call_00_dD2BLuNeJCTh2iiYC1QR3449","name":"workflow","arguments":"{\"meta\": {\"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\"}, \"script\": \"\\nphase('Run')\\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\\nreturn { reply }\\n\"}"}} +{"type":"tool/result","seq":161,"time":1783600638304,"data":{"turn":1,"step":1,"callId":"call_00_dD2BLuNeJCTh2iiYC1QR3449","content":[{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WF_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[160],"surfaceOp":"append"} +{"type":"step/end","seq":162,"time":1783600638304,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":163,"time":1783600638305,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":164,"time":1783600640028,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":165,"time":1783600640028,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":166,"time":1783600640134,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" workflow"}}} +{"type":"assistant/chunk","seq":167,"time":1783600640162,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" returned"}}} +{"type":"assistant/chunk","seq":168,"time":1783600640195,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" successfully"}}} +{"type":"assistant/chunk","seq":169,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":170,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":171,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":172,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":173,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WF"}}} +{"type":"assistant/chunk","seq":174,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_CH"}}} +{"type":"assistant/chunk","seq":175,"time":1783600640862,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ILD"}}} +{"type":"assistant/chunk","seq":176,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":177,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":178,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Now"}}} +{"type":"assistant/chunk","seq":179,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":180,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} +{"type":"assistant/chunk","seq":181,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":182,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":183,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":184,"time":1783600640864,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":185,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":186,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WORK"}}} +{"type":"assistant/chunk","seq":187,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"FL"}}} +{"type":"assistant/chunk","seq":188,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OW"}}} +{"type":"assistant/chunk","seq":189,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_D"}}} +{"type":"assistant/chunk","seq":190,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":191,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}} +{"type":"assistant/chunk","seq":192,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":193,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":194,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":195,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":196,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WORK"}}} +{"type":"assistant/chunk","seq":197,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"FL"}}} +{"type":"assistant/chunk","seq":198,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OW"}}} +{"type":"assistant/chunk","seq":199,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_D"}}} +{"type":"assistant/chunk","seq":200,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":201,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly \"WORKFLOW_DONE\" and stop."}}}} +{"type":"assistant/chunk","seq":202,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WORKFLOW_DONE"}}}} +{"type":"assistant/chunk","seq":203,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":328,"outputTokens":36,"cacheReadTokens":3072,"reasoningTokens":30}}}} +{"type":"assistant/chunk","seq":204,"time":1783600640865,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":205,"time":1783600640865,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly \"WORKFLOW_DONE\" and stop."},{"type":"text","text":"WORKFLOW_DONE"}],"usage":{"inputTokens":328,"outputTokens":36,"cacheReadTokens":3072,"reasoningTokens":30}},"sourceEventSeqs":[164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204],"surfaceOp":"append"} +{"type":"step/end","seq":206,"time":1783600640865,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":207,"time":1783600640865,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl index 49eeb48918..63af2375d5 100644 --- a/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/workflow-run/stdout.golden.jsonl @@ -5,35 +5,91 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" use"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exact"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" workflow"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" once"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" specific"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" parameters"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" carefully"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" follow"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" instructions"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" args"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" omitted"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ("}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"so"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" don"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'t"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" include"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":")\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" meta"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ="}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" {"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"name"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\":"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"sn"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"apshot"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"-flow"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"description"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\":"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"one"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" child"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" for"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" snapshot"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" }\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" script"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" provided"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" then"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" ="}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" given"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" verb"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"atim"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" After"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WORK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"FL"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OW"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_D"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" do"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" this"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" instructed"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Vp9f0l50KeeHRfcBezz08251","title":"workflow: snapshot-flow","kind":"other","status":"in_progress","rawInput":"export const meta = { name: 'snapshot-flow', description: 'one child for the snapshot' }\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }"}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Vp9f0l50KeeHRfcBezz08251","status":"completed","content":[{"type":"content","content":{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WF_CHILD_OK\"\n}"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_dD2BLuNeJCTh2iiYC1QR3449","title":"workflow: snapshot-flow","kind":"other","status":"in_progress","rawInput":"\nphase('Run')\nconst reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.')\nreturn { reply }\n"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_dD2BLuNeJCTh2iiYC1QR3449","status":"completed","content":[{"type":"content","content":{"type":"text","text":"workflow \"snapshot-flow\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WF_CHILD_OK\"\n}"}}]}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" workflow"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returned"}}}} @@ -53,16 +109,16 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORK"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WORK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"FL"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OW"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_D"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" instructed"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"WORK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"FL"}}}} From 2c03b2bc29d0bbea7a4d0bfd3a63db3496015492 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 20:56:44 +0800 Subject: [PATCH 103/119] feat: surface the run_code program in the ACP tool-call card MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The generated program rode only rawInput — the detail/expanded slot many ACP clients never open — so the code a run executed was invisible in the UI stream. presentCall now also carries it as a fenced ts block in the card's content, which the bridge already forwards as tool_call content. The two code-mode snapshot goldens are re-recorded live and replay green; the presentation unit test pins the fenced block. --- .../snapshots/both-mode-turn/session.jsonl | 232 ++++++----- .../both-mode-turn/stdout.golden.jsonl | 15 +- .../snapshots/code-mode-turn/session.jsonl | 377 +++++++++--------- .../code-mode-turn/stdout.golden.jsonl | 65 ++- packages/core/tools/src/code-mode.ts | 12 +- packages/core/tools/tests/code-mode.spec.ts | 10 +- 6 files changed, 359 insertions(+), 352 deletions(-) diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl index a2b0e9921b..c7bf7c3eba 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl @@ -1,110 +1,122 @@ -{"type":"session","version":0,"id":"55c51419-0ee3-4c06-8199-cc69eef57a45","createdAt":1783484575071,"cwd":"/tmp/acp-snap-cwd-lORmOD"} -{"type":"turn/start","seq":0,"time":1783484575075,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783484575076,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783484575078,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783484575079,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-lORmOD.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783484575489,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783484575489,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783484575561,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783484575587,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783484575587,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783484575588,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783484575588,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} -{"type":"assistant/chunk","seq":11,"time":1783484575588,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":12,"time":1783484575613,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} -{"type":"assistant/chunk","seq":13,"time":1783484575614,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":14,"time":1783484575614,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":15,"time":1783484575614,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":16,"time":1783484575639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":17,"time":1783484575639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" runs"}}} -{"type":"assistant/chunk","seq":18,"time":1783484575639,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":19,"time":1783484575662,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":20,"time":1783484575663,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} -{"type":"assistant/chunk","seq":21,"time":1783484575663,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} -{"type":"assistant/chunk","seq":22,"time":1783484575663,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":23,"time":1783484575688,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} -{"type":"assistant/chunk","seq":24,"time":1783484575688,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" via"}}} -{"type":"assistant/chunk","seq":25,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} -{"type":"assistant/chunk","seq":26,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} -{"type":"assistant/chunk","seq":27,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} -{"type":"assistant/chunk","seq":28,"time":1783484575689,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":29,"time":1783484575713,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} -{"type":"assistant/chunk","seq":30,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":31,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":32,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":33,"time":1783484575714,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} -{"type":"assistant/chunk","seq":34,"time":1783484575739,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":35,"time":1783484575739,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}} -{"type":"assistant/chunk","seq":36,"time":1783484575739,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":37,"time":1783484575740,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":38,"time":1783484575815,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":39,"time":1783484575815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":40,"time":1783484575840,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":41,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":42,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"code"}}} -{"type":"assistant/chunk","seq":43,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":44,"time":1783484575841,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":45,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":46,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":47,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":48,"time":1783484575865,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":49,"time":1783484575890,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":50,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":51,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":52,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":53,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":54,"time":1783484575891,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":55,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":56,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" B"}}} -{"type":"assistant/chunk","seq":57,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"OTH"}}} -{"type":"assistant/chunk","seq":58,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":59,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":60,"time":1783484575916,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":61,"time":1783484575942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":62,"time":1783484575942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":63,"time":1783484575942,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":64,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":65,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" B"}}} -{"type":"assistant/chunk","seq":66,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"OTH"}}} -{"type":"assistant/chunk","seq":67,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":68,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":69,"time":1783484576004,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":" }"}}} -{"type":"assistant/chunk","seq":70,"time":1783484576019,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":");"}}} -{"type":"assistant/chunk","seq":71,"time":1783484576019,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":72,"time":1783484576044,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":73,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns the output. Let me do that."}}}} -{"type":"assistant/chunk","seq":74,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","arguments":"{\"code\": \"return await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\"}"}}}} -{"type":"assistant/chunk","seq":75,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3733,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":33}}}} -{"type":"assistant/chunk","seq":76,"time":1783484576075,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":77,"time":1783484576078,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns the output. Let me do that."},{"type":"tool-call","id":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","arguments":"{\"code\": \"return await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\"}"}],"usage":{"inputTokens":3733,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":33}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76],"surfaceOp":"append"} -{"type":"tool/call","seq":78,"time":1783484576078,"data":{"turn":1,"step":1,"callId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","name":"run_code","arguments":"{\"code\": \"return await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\"}"}} -{"type":"tool/code-dispatch","seq":79,"time":1783484576205,"data":{"parentCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","subCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK"},"isError":false,"resultSummary":"BOTH_OK\n"}} -{"type":"tool/result","seq":80,"time":1783484576208,"data":{"turn":1,"step":1,"callId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[78],"surfaceOp":"append"} -{"type":"step/end","seq":81,"time":1783484576208,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":82,"time":1783484576209,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":83,"time":1783484576645,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":84,"time":1783484576645,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":85,"time":1783484576758,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":86,"time":1783484576782,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} -{"type":"assistant/chunk","seq":87,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":88,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} -{"type":"assistant/chunk","seq":89,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} -{"type":"assistant/chunk","seq":90,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":91,"time":1783484576783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} -{"type":"assistant/chunk","seq":92,"time":1783484576810,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} -{"type":"assistant/chunk","seq":93,"time":1783484576835,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":94,"time":1783484576836,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":95,"time":1783484576836,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":96,"time":1783484576836,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":97,"time":1783484576860,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":98,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":99,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} -{"type":"assistant/chunk","seq":100,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} -{"type":"assistant/chunk","seq":101,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} -{"type":"assistant/chunk","seq":102,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is \"BOTH_OK\". Let me reply with that."}}}} -{"type":"assistant/chunk","seq":103,"time":1783484576894,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} -{"type":"assistant/chunk","seq":104,"time":1783484576895,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":138,"outputTokens":18,"cacheReadTokens":3712,"reasoningTokens":14}}}} -{"type":"assistant/chunk","seq":105,"time":1783484576895,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":106,"time":1783484576895,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is \"BOTH_OK\". Let me reply with that."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":138,"outputTokens":18,"cacheReadTokens":3712,"reasoningTokens":14}},"sourceEventSeqs":[83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105],"surfaceOp":"append"} -{"type":"step/end","seq":107,"time":1783484576895,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":108,"time":1783484576895,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"14b611ba-2cfd-46d6-bdcb-4f12a261f651","createdAt":1783600817605,"cwd":"/tmp/acp-snap-cwd-f5yZEg"} +{"type":"turn/start","seq":0,"time":1783600817609,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783600817610,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783600817612,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783600817613,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-f5yZEg.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783600818106,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783600818107,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783600818317,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783600818345,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783600818346,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783600818346,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783600818347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} +{"type":"assistant/chunk","seq":11,"time":1783600818347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":12,"time":1783600818347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":13,"time":1783600818374,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":14,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":15,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":16,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":17,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" runs"}}} +{"type":"assistant/chunk","seq":18,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":19,"time":1783600818407,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":20,"time":1783600818407,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} +{"type":"assistant/chunk","seq":21,"time":1783600818407,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":22,"time":1783600818408,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":23,"time":1783600818432,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":24,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" via"}}} +{"type":"assistant/chunk","seq":25,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} +{"type":"assistant/chunk","seq":26,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} +{"type":"assistant/chunk","seq":27,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} +{"type":"assistant/chunk","seq":28,"time":1783600818434,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":29,"time":1783600818461,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} +{"type":"assistant/chunk","seq":30,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" its"}}} +{"type":"assistant/chunk","seq":31,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":32,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":33,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":34,"time":1783600818491,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":35,"time":1783600818491,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}} +{"type":"assistant/chunk","seq":36,"time":1783600818492,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":37,"time":1783600818492,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":38,"time":1783600818583,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":39,"time":1783600818583,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":40,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":41,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":42,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":43,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":44,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":45,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":46,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":47,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" result"}}} +{"type":"assistant/chunk","seq":48,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":49,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":50,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":51,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":52,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":53,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"({\\n"}}} +{"type":"assistant/chunk","seq":54,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" "}}} +{"type":"assistant/chunk","seq":55,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":56,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":57,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":58,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":59,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":60,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":61,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":62,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\\\",\\n"}}} +{"type":"assistant/chunk","seq":63,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" "}}} +{"type":"assistant/chunk","seq":64,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":65,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":66,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":67,"time":1783600818757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":68,"time":1783600818785,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":69,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":70,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":71,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":72,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" string"}}} +{"type":"assistant/chunk","seq":73,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\\\"\\n"}}} +{"type":"assistant/chunk","seq":74,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"});\\n"}}} +{"type":"assistant/chunk","seq":75,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":76,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" result"}}} +{"type":"assistant/chunk","seq":77,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":";"}}} +{"type":"assistant/chunk","seq":78,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":79,"time":1783600818845,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":80,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns its output. Let me do that."}}}} +{"type":"assistant/chunk","seq":81,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK string\\\"\\n});\\nreturn result;\"}"}}}} +{"type":"assistant/chunk","seq":82,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3734,"outputTokens":107,"cacheReadTokens":0,"reasoningTokens":33}}}} +{"type":"assistant/chunk","seq":83,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":84,"time":1783600818909,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns its output. Let me do that."},{"type":"tool-call","id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK string\\\"\\n});\\nreturn result;\"}"}],"usage":{"inputTokens":3734,"outputTokens":107,"cacheReadTokens":0,"reasoningTokens":33}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83],"surfaceOp":"append"} +{"type":"tool/call","seq":85,"time":1783600818909,"data":{"turn":1,"step":1,"callId":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK string\\\"\\n});\\nreturn result;\"}"}} +{"type":"tool/code-dispatch","seq":86,"time":1783600819019,"data":{"parentCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326","subCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK string"},"isError":false,"resultSummary":"BOTH_OK\n"}} +{"type":"tool/result","seq":87,"time":1783600819021,"data":{"turn":1,"step":1,"callId":"call_00_Kv45KGQIqVt8nuaRebYh2326","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[85],"surfaceOp":"append"} +{"type":"step/end","seq":88,"time":1783600819022,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":89,"time":1783600819022,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":90,"time":1783600819418,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":91,"time":1783600819418,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":92,"time":1783600819515,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":93,"time":1783600819543,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":94,"time":1783600819544,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":95,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} +{"type":"assistant/chunk","seq":96,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":97,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":98,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":99,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":100,"time":1783600819575,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} +{"type":"assistant/chunk","seq":101,"time":1783600819602,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":102,"time":1783600819603,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":103,"time":1783600819603,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":104,"time":1783600819603,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":105,"time":1783600819634,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":106,"time":1783600819635,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} +{"type":"assistant/chunk","seq":107,"time":1783600819635,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":108,"time":1783600819664,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":109,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":110,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":111,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} +{"type":"assistant/chunk","seq":112,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} +{"type":"assistant/chunk","seq":113,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} +{"type":"assistant/chunk","seq":114,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is \"BOTH_OK\". I need to reply with that output only and stop."}}}} +{"type":"assistant/chunk","seq":115,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} +{"type":"assistant/chunk","seq":116,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3840,"reasoningTokens":19}}}} +{"type":"assistant/chunk","seq":117,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":118,"time":1783600819694,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is \"BOTH_OK\". I need to reply with that output only and stop."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3840,"reasoningTokens":19}},"sourceEventSeqs":[90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117],"surfaceOp":"append"} +{"type":"step/end","seq":119,"time":1783600819694,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":120,"time":1783600819694,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl index d307e1d60f..4a959143d7 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl @@ -25,7 +25,7 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} @@ -33,8 +33,8 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" do"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","title":"Run code","kind":"execute","status":"in_progress","rawInput":"return await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });"}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_fwre7Dvt0ZU6p96bEBdk6728","status":"completed","content":[{"type":"content","content":{"type":"text","text":"BOTH_OK\n"}}],"title":"Run code (1 tool call)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK string\"\n});\nreturn result;","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK string\"\n});\nreturn result;\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326","status":"completed","content":[{"type":"content","content":{"type":"text","text":"BOTH_OK\n"}}],"title":"Run code (1 tool call)"}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} @@ -43,11 +43,16 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OTH"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" only"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"B"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"OTH"}}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl index dd9c0bed28..97d73709fc 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl @@ -1,196 +1,181 @@ -{"type":"session","version":0,"id":"92c80cd8-dddc-4cd6-a05a-9676ef54af5e","createdAt":1783484558135,"cwd":"/tmp/acp-snap-cwd-zej9wx"} -{"type":"turn/start","seq":0,"time":1783484558139,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783484558139,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783484558142,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783484558142,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-zej9wx.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783484558789,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783484558789,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783484558877,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783484558904,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783484558905,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783484558905,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783484558905,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} -{"type":"assistant/chunk","seq":11,"time":1783484558933,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":12,"time":1783484558933,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} -{"type":"assistant/chunk","seq":13,"time":1783484558934,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":14,"time":1783484558934,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} -{"type":"assistant/chunk","seq":15,"time":1783484558934,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":16,"time":1783484558957,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":17,"time":1783484558957,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}} -{"type":"assistant/chunk","seq":18,"time":1783484558958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}} -{"type":"assistant/chunk","seq":19,"time":1783484558958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":20,"time":1783484558958,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} -{"type":"assistant/chunk","seq":21,"time":1783484558982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} -{"type":"assistant/chunk","seq":22,"time":1783484558982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":23,"time":1783484558982,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":24,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":25,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":26,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} -{"type":"assistant/chunk","seq":27,"time":1783484559009,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":28,"time":1783484559035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} -{"type":"assistant/chunk","seq":29,"time":1783484559035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}} -{"type":"assistant/chunk","seq":30,"time":1783484559035,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":31,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} -{"type":"assistant/chunk","seq":32,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} -{"type":"assistant/chunk","seq":33,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":34,"time":1783484559036,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":35,"time":1783484559060,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":36,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":37,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} -{"type":"assistant/chunk","seq":38,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} -{"type":"assistant/chunk","seq":39,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} -{"type":"assistant/chunk","seq":40,"time":1783484559061,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}} -{"type":"assistant/chunk","seq":41,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":42,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Returns"}}} -{"type":"assistant/chunk","seq":43,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":44,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} -{"type":"assistant/chunk","seq":45,"time":1783484559088,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} -{"type":"assistant/chunk","seq":46,"time":1783484559089,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} -{"type":"assistant/chunk","seq":47,"time":1783484559114,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":48,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":49,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} -{"type":"assistant/chunk","seq":50,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} -{"type":"assistant/chunk","seq":51,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}} -{"type":"assistant/chunk","seq":52,"time":1783484559115,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Then"}}} -{"type":"assistant/chunk","seq":53,"time":1783484559186,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":54,"time":1783484559187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":55,"time":1783484559187,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}} -{"type":"assistant/chunk","seq":56,"time":1783484559201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":57,"time":1783484559201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} -{"type":"assistant/chunk","seq":58,"time":1783484559201,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} -{"type":"assistant/chunk","seq":59,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".\n\n"}}} -{"type":"assistant/chunk","seq":60,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} -{"type":"assistant/chunk","seq":61,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":62,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} -{"type":"assistant/chunk","seq":63,"time":1783484559227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":64,"time":1783484559251,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" code"}}} -{"type":"assistant/chunk","seq":65,"time":1783484559252,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":66,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":67,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":68,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":69,"time":1783484559330,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":70,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"code"}}} -{"type":"assistant/chunk","seq":71,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":72,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":73,"time":1783484559357,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":74,"time":1783484559382,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":75,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":76,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"1"}}} -{"type":"assistant/chunk","seq":77,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":78,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":79,"time":1783484559383,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":80,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":81,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":82,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":83,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":84,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":85,"time":1783484559410,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":86,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":87,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":88,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_"}}} -{"type":"assistant/chunk","seq":89,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ONE"}}} -{"type":"assistant/chunk","seq":90,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":91,"time":1783484559435,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":92,"time":1783484559461,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":93,"time":1783484559461,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":94,"time":1783484559461,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":95,"time":1783484559489,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":96,"time":1783484559489,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":97,"time":1783484559489,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_"}}} -{"type":"assistant/chunk","seq":98,"time":1783484559515,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ONE"}}} -{"type":"assistant/chunk","seq":99,"time":1783484559515,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":100,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" });\\n"}}} -{"type":"assistant/chunk","seq":101,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":102,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":103,"time":1783484559516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"2"}}} -{"type":"assistant/chunk","seq":104,"time":1783484559541,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":105,"time":1783484559541,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":106,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":107,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":108,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":109,"time":1783484559542,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":110,"time":1783484559566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":111,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":112,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":113,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":114,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":115,"time":1783484559567,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_T"}}} -{"type":"assistant/chunk","seq":116,"time":1783484559592,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"WO"}}} -{"type":"assistant/chunk","seq":117,"time":1783484559592,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":118,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":119,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":120,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":121,"time":1783484559593,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":122,"time":1783484559617,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":123,"time":1783484559617,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":124,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"_T"}}} -{"type":"assistant/chunk","seq":125,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"WO"}}} -{"type":"assistant/chunk","seq":126,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":127,"time":1783484559618,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" });\\n"}}} -{"type":"assistant/chunk","seq":128,"time":1783484559643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":129,"time":1783484559644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":130,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"1"}}} -{"type":"assistant/chunk","seq":131,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".trim"}}} -{"type":"assistant/chunk","seq":132,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"()"}}} -{"type":"assistant/chunk","seq":133,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" +"}}} -{"type":"assistant/chunk","seq":134,"time":1783484559669,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" \\\"+"}}} -{"type":"assistant/chunk","seq":135,"time":1783484559697,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":136,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" +"}}} -{"type":"assistant/chunk","seq":137,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":138,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"2"}}} -{"type":"assistant/chunk","seq":139,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":".trim"}}} -{"type":"assistant/chunk","seq":140,"time":1783484559698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"();"}}} -{"type":"assistant/chunk","seq":141,"time":1783484559724,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":142,"time":1783484559725,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":143,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash with `echo CODE_ONE`\n2. Calls bash with `echo CODE_TWO`\n3. Returns the two outputs joined with a plus sign\n\nThen reply with just that joined string.\n\nLet me write the code."}}}} -{"type":"assistant/chunk","seq":144,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}} -{"type":"assistant/chunk","seq":145,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2121,"outputTokens":171,"cacheReadTokens":0,"reasoningTokens":61}}}} -{"type":"assistant/chunk","seq":146,"time":1783484559777,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":147,"time":1783484559780,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash with `echo CODE_ONE`\n2. Calls bash with `echo CODE_TWO`\n3. Returns the two outputs joined with a plus sign\n\nThen reply with just that joined string.\n\nLet me write the code."},{"type":"tool-call","id":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"usage":{"inputTokens":2121,"outputTokens":171,"cacheReadTokens":0,"reasoningTokens":61}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146],"surfaceOp":"append"} -{"type":"tool/call","seq":148,"time":1783484559780,"data":{"turn":1,"step":1,"callId":"call_00_TBMd5LxIFwxqRBHOErfg0279","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}} -{"type":"tool/code-dispatch","seq":149,"time":1783484559896,"data":{"parentCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","subCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo CODE_ONE"},"isError":false,"resultSummary":"CODE_ONE\n"}} -{"type":"tool/code-dispatch","seq":150,"time":1783484559908,"data":{"parentCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","subCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo CODE_TWO"},"isError":false,"resultSummary":"CODE_TWO\n"}} -{"type":"tool/result","seq":151,"time":1783484559913,"data":{"turn":1,"step":1,"callId":"call_00_TBMd5LxIFwxqRBHOErfg0279","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[148],"surfaceOp":"append"} -{"type":"step/end","seq":152,"time":1783484559913,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":153,"time":1783484559914,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":154,"time":1783484560545,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":155,"time":1783484560545,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":156,"time":1783484560716,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" result"}}} -{"type":"assistant/chunk","seq":157,"time":1783484560744,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} -{"type":"assistant/chunk","seq":158,"time":1783484560744,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":159,"time":1783484560769,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} -{"type":"assistant/chunk","seq":160,"time":1783484560770,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} -{"type":"assistant/chunk","seq":161,"time":1783484560795,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} -{"type":"assistant/chunk","seq":162,"time":1783484560822,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} -{"type":"assistant/chunk","seq":163,"time":1783484560823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":164,"time":1783484560823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} -{"type":"assistant/chunk","seq":165,"time":1783484560823,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} -{"type":"assistant/chunk","seq":166,"time":1783484560847,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":167,"time":1783484560847,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} -{"type":"assistant/chunk","seq":168,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} -{"type":"assistant/chunk","seq":169,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} -{"type":"assistant/chunk","seq":170,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} -{"type":"assistant/chunk","seq":171,"time":1783484560848,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"`."}}} -{"type":"assistant/chunk","seq":172,"time":1783484560872,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} -{"type":"assistant/chunk","seq":173,"time":1783484560872,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"'ll"}}} -{"type":"assistant/chunk","seq":174,"time":1783484560898,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":175,"time":1783484560898,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":176,"time":1783484560898,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}} -{"type":"assistant/chunk","seq":177,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":178,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} -{"type":"assistant/chunk","seq":179,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":180,"time":1783484560924,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":181,"time":1783484560925,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} -{"type":"assistant/chunk","seq":182,"time":1783484560925,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} -{"type":"assistant/chunk","seq":183,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} -{"type":"assistant/chunk","seq":184,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} -{"type":"assistant/chunk","seq":185,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} -{"type":"assistant/chunk","seq":186,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} -{"type":"assistant/chunk","seq":187,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} -{"type":"assistant/chunk","seq":188,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The result is exactly what was requested: `CODE_ONE+CODE_TWO`. I'll reply with just that string."}}}} -{"type":"assistant/chunk","seq":189,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} -{"type":"assistant/chunk","seq":190,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":135,"outputTokens":33,"cacheReadTokens":2176,"reasoningTokens":25}}}} -{"type":"assistant/chunk","seq":191,"time":1783484560950,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":192,"time":1783484560951,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The result is exactly what was requested: `CODE_ONE+CODE_TWO`. I'll reply with just that string."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":135,"outputTokens":33,"cacheReadTokens":2176,"reasoningTokens":25}},"sourceEventSeqs":[154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191],"surfaceOp":"append"} -{"type":"step/end","seq":193,"time":1783484560951,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":194,"time":1783484560951,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"9423eeec-62a7-46ea-8b05-abd52ac1e703","createdAt":1783600811133,"cwd":"/tmp/acp-snap-cwd-bdz41V"} +{"type":"turn/start","seq":0,"time":1783600811137,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783600811138,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783600811141,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783600811141,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-bdz41V.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783600811872,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783600811872,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783600812033,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783600812066,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} +{"type":"assistant/chunk","seq":11,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":12,"time":1783600812068,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} +{"type":"assistant/chunk","seq":13,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} +{"type":"assistant/chunk","seq":14,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}} +{"type":"assistant/chunk","seq":15,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":16,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":17,"time":1783600812121,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":18,"time":1783600812121,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":19,"time":1783600812121,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":20,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":21,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":22,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":23,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":24,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":25,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":26,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":27,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":28,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`,"}}} +{"type":"assistant/chunk","seq":29,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}} +{"type":"assistant/chunk","seq":30,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}} +{"type":"assistant/chunk","seq":31,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":32,"time":1783600812208,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} +{"type":"assistant/chunk","seq":33,"time":1783600812208,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} +{"type":"assistant/chunk","seq":34,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} +{"type":"assistant/chunk","seq":35,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":36,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":37,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} +{"type":"assistant/chunk","seq":38,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} +{"type":"assistant/chunk","seq":39,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":40,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":41,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":42,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":43,"time":1783600812267,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":44,"time":1783600812267,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":45,"time":1783600812267,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":46,"time":1783600812296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":47,"time":1783600812296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":48,"time":1783600812296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":49,"time":1783600812388,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":50,"time":1783600812389,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":51,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":52,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":53,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":54,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":55,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":56,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":57,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":58,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":59,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":60,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":61,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":62,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":63,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":64,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":65,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":66,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":67,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":68,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":69,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":70,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":71,"time":1783600812507,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":72,"time":1783600812536,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":73,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":74,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":75,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":76,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":77,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":78,"time":1783600812566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":79,"time":1783600812566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" first"}}} +{"type":"assistant/chunk","seq":80,"time":1783600812566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" code"}}} +{"type":"assistant/chunk","seq":81,"time":1783600812595,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":82,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":83,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":84,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":85,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":86,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":87,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":88,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":89,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":90,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":91,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":92,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":93,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":94,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":95,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":96,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":97,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":98,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":99,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":100,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":101,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":102,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":103,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":104,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":105,"time":1783600812714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" second"}}} +{"type":"assistant/chunk","seq":106,"time":1783600812714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" code"}}} +{"type":"assistant/chunk","seq":107,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":108,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":109,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":110,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":111,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":112,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":113,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"()"}}} +{"type":"assistant/chunk","seq":114,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":115,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\"+"}}} +{"type":"assistant/chunk","seq":116,"time":1783600812772,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":117,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":118,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":119,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":120,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":121,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"();"}}} +{"type":"assistant/chunk","seq":122,"time":1783600812802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":123,"time":1783600812802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":124,"time":1783600812863,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call the bash tool twice with `echo CODE_ONE` and `echo CODE_TWO`, then return the two outputs joined with a plus sign. Let me write a single run_code program."}}}} +{"type":"assistant/chunk","seq":125,"time":1783600812863,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo first code\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo second code\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}} +{"type":"assistant/chunk","seq":126,"time":1783600812864,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2121,"outputTokens":152,"cacheReadTokens":0,"reasoningTokens":44}}}} +{"type":"assistant/chunk","seq":127,"time":1783600812864,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":128,"time":1783600812866,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call the bash tool twice with `echo CODE_ONE` and `echo CODE_TWO`, then return the two outputs joined with a plus sign. Let me write a single run_code program."},{"type":"tool-call","id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo first code\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo second code\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"usage":{"inputTokens":2121,"outputTokens":152,"cacheReadTokens":0,"reasoningTokens":44}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127],"surfaceOp":"append"} +{"type":"tool/call","seq":129,"time":1783600812866,"data":{"turn":1,"step":1,"callId":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo first code\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo second code\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}} +{"type":"tool/code-dispatch","seq":130,"time":1783600812976,"data":{"parentCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","subCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo first code"},"isError":false,"resultSummary":"CODE_ONE\n"}} +{"type":"tool/code-dispatch","seq":131,"time":1783600812986,"data":{"parentCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","subCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo second code"},"isError":false,"resultSummary":"CODE_TWO\n"}} +{"type":"tool/result","seq":132,"time":1783600812988,"data":{"turn":1,"step":1,"callId":"call_00_RJaLT7yuWS9RqjyD9wP85417","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[129],"surfaceOp":"append"} +{"type":"step/end","seq":133,"time":1783600812989,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":134,"time":1783600812989,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":135,"time":1783600813658,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":136,"time":1783600813658,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":137,"time":1783600813840,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":138,"time":1783600813843,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" returned"}}} +{"type":"assistant/chunk","seq":139,"time":1783600813843,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":140,"time":1783600813871,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} +{"type":"assistant/chunk","seq":141,"time":1783600813900,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} +{"type":"assistant/chunk","seq":142,"time":1783600813929,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} +{"type":"assistant/chunk","seq":143,"time":1783600813929,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} +{"type":"assistant/chunk","seq":144,"time":1783600813929,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":145,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":146,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":147,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":148,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} +{"type":"assistant/chunk","seq":149,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":150,"time":1783600813959,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":151,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":152,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"`."}}} +{"type":"assistant/chunk","seq":153,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":154,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} +{"type":"assistant/chunk","seq":155,"time":1783600814016,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":156,"time":1783600814017,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":157,"time":1783600814017,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":158,"time":1783600814017,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":159,"time":1783600814045,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} +{"type":"assistant/chunk","seq":160,"time":1783600814045,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} +{"type":"assistant/chunk","seq":161,"time":1783600814046,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} +{"type":"assistant/chunk","seq":162,"time":1783600814046,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":163,"time":1783600814131,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":164,"time":1783600814131,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":165,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":166,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":167,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} +{"type":"assistant/chunk","seq":168,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":169,"time":1783600814136,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} +{"type":"assistant/chunk","seq":170,"time":1783600814136,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":171,"time":1783600814136,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} +{"type":"assistant/chunk","seq":172,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} +{"type":"assistant/chunk","seq":173,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The program returned exactly what was requested: `CODE_ONE+CODE_TWO`. I need to reply with that joined string only and stop."}}}} +{"type":"assistant/chunk","seq":174,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} +{"type":"assistant/chunk","seq":175,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":116,"outputTokens":37,"cacheReadTokens":2176,"reasoningTokens":29}}}} +{"type":"assistant/chunk","seq":176,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":177,"time":1783600814137,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The program returned exactly what was requested: `CODE_ONE+CODE_TWO`. I need to reply with that joined string only and stop."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":116,"outputTokens":37,"cacheReadTokens":2176,"reasoningTokens":29}},"sourceEventSeqs":[135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176],"surfaceOp":"append"} +{"type":"step/end","seq":178,"time":1783600814137,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":179,"time":1783600814138,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl index 3660515e4c..916f20126c 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl @@ -5,39 +5,27 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" call"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" twice"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Returns"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`,"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" then"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" outputs"}}}} @@ -46,26 +34,21 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" plus"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sign"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Then"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".\n\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();"}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_TBMd5LxIFwxqRBHOErfg0279","status":"completed","content":[{"type":"content","content":{"type":"text","text":"CODE_ONE+CODE_TWO"}}],"title":"Run code (2 tool calls)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo first code\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo second code\" });\nreturn out1.trim() + \"+\" + out2.trim();","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo first code\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo second code\" });\nreturn out1.trim() + \"+\" + out2.trim();\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","status":"completed","content":[{"type":"content","content":{"type":"text","text":"CODE_ONE+CODE_TWO"}}],"title":"Run code (2 tool calls)"}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" result"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returned"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" was"}}}} @@ -81,12 +64,16 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'ll"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" only"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_"}}}} diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index 404364d57c..1ae26a5eb9 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -289,7 +289,17 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => exec.signal?.removeEventListener('abort', onOuterAbort) } }, - presentCall: args => ({ card: 'generic', title: 'Run code', kind: 'execute', rawInput: args.code }), + // The program IS the call: surface it as an always-visible fenced block in + // the card body (rawInput alone lands in detail/expanded views many + // clients never open). Fence collisions are impossible to break rendering + // — a backtick run inside the program at worst ends the block early. + presentCall: args => ({ + card: 'generic', + title: 'Run code', + kind: 'execute', + rawInput: args.code, + content: [{ type: 'text', text: `\`\`\`ts\n${args.code}\n\`\`\`` }], + }), presentResult: (_args, result) => { const meta = asRunCodeMeta(result.meta) if (!meta) return undefined diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index 03afc260ee..092e0ed90e 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -447,7 +447,15 @@ describe('the run_code dispatch bridge', () => { it('presents the pending call as a generic execute card carrying the program, and the result with the captured output', async () => { const { ctx } = await setup({ mode: 'code' }) const tool = ctx.tools.get(RUN_CODE_NAME)! - expect(tool.presentCall?.({ code: 'return 1' })).toEqual({ card: 'generic', title: 'Run code', kind: 'execute', rawInput: 'return 1' }) + expect(tool.presentCall?.({ code: 'return 1' })).toEqual({ + card: 'generic', + title: 'Run code', + kind: 'execute', + rawInput: 'return 1', + // The program rides the card BODY as a fenced block — visible in ACP + // clients that never open the rawInput detail view. + content: [{ type: 'text', text: '```ts\nreturn 1\n```' }], + }) const view = tool.presentResult?.({ code: 'return 1' }, { content: [{ type: 'text', text: 'model-facing' }], isError: false, From 6f86f6081b1818614a48a87765d394dada689781 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:14:30 +0800 Subject: [PATCH 104/119] workflow: dispose() host-drives child disposal inside the grace --- .../workflow/workflow-workerthread/README.md | 2 +- .../workflow-workerthread/src/host.ts | 90 ++++++++++++------- .../tests/workflow-workerthread.spec.ts | 62 ++++++++++++- 3 files changed, 119 insertions(+), 35 deletions(-) diff --git a/packages/workflow/workflow-workerthread/README.md b/packages/workflow/workflow-workerthread/README.md index 25c79ad09c..dc8859d351 100644 --- a/packages/workflow/workflow-workerthread/README.md +++ b/packages/workflow/workflow-workerthread/README.md @@ -32,7 +32,7 @@ Values LEAVING the script (hook options/schemas, the script's return) are materi Per-run limits: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` posts the cancel to the worker (its hooks start throwing `CANCELLED`; the script dies at its next await) and cancels every host-side child NOW on **both seam channels** — the shared request signal aborts AND each registered child's explicit `cancel()` is called host-side, because the seam leaves a provider free to honor either channel and a worker wedged in a synchronous spin could not relay its own per-child cancel RPCs (those later land as idempotent no-ops). The grace then arms: a run still unsettled `disposeGraceMs` later force-settles `cancelled` and the worker is **terminated**. A cancellation that lands before the body runs (the ready→go handshake) reports `cancelled` without executing anything; a worker `result` racing an in-flight host cancellation reports `cancelled` too (first-wins settlement — the seam-visible result had not settled when cancellation was requested); post-cancel `phase`/`log` narration is suppressed host-side, while cancelled children still deliver their paired `agent-end`. -A worker that dies unexpectedly (an OOM, a script reaching `process.exit` through the documented vm escape) settles the run `stopReason: 'error'` with the exit diagnostics — or `'cancelled'` when a cancel was in flight — and the host-side child registry is what winds every surviving child down. `dispose()` = cancel + bounded wait (result, then child-registry quiescence, capped by the grace) + unconditional `worker.terminate()`: the thread never outlives its run. Once a run settles, stray children a script fired without awaiting are cancelled too, and `dispose()` waits for their disposal (bounded by the grace) before returning. +A worker that dies unexpectedly (an OOM, a script reaching `process.exit` through the documented vm escape) settles the run `stopReason: 'error'` with the exit diagnostics — or `'cancelled'` when a cancel was in flight — and the host-side child registry is what winds every surviving child down. `dispose()` = cancel + immediate host-driven disposal of every registered child (a wedged worker can relay no dispose RPC, so child teardown overlaps the grace instead of starting after it; the worker's own dispose RPCs join the same per-child disposal) + bounded wait (result, then child-registry quiescence, capped by the grace) + unconditional `worker.terminate()`: the thread never outlives its run. Once a run settles, stray children a script fired without awaiting are cancelled too, and `dispose()` waits for their disposal (bounded by the grace) before returning. **Engine-specific limitations**: worker startup is paid per run; on a termination path `agentsStarted` reports the HOST-observed count (accepted `child-start`s — calls still queued worker-side for a concurrency slot are unknowable then); and a returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — with the value-boundary guard applying to the resolution. diff --git a/packages/workflow/workflow-workerthread/src/host.ts b/packages/workflow/workflow-workerthread/src/host.ts index 9d98d00933..c512c15dee 100644 --- a/packages/workflow/workflow-workerthread/src/host.ts +++ b/packages/workflow/workflow-workerthread/src/host.ts @@ -15,9 +15,14 @@ * terminated — the real kill an in-process engine could not perform). * * Children live in a host-side registry (callId → run): the worker drives - * their disposal by RPC on the graceful path, and the registry is what lets - * the host abort and dispose every survivor when the worker dies or is - * terminated mid-flight. On a termination path `agentsStarted` reports the + * their disposal by RPC on the graceful path, `dispose()` host-drives every + * registered child's disposal immediately (a wedged worker can relay no + * dispose RPC, and child teardown must overlap the grace, not start after + * it), and the registry is what lets the host abort and dispose every + * survivor when the worker dies or is terminated mid-flight. The three + * paths share ONE disposal per child (memoized by callId; the seam's + * dispose() is idempotent anyway, the memo keeps the bookkeeping and the + * containment warn single). On a termination path `agentsStarted` reports the * HOST-observed count (accepted `child-start` messages) — `agent()` calls * still queued worker-side for a concurrency slot are unknowable then; the * worker's own count rides the result message on every graceful path. @@ -85,6 +90,8 @@ export class WorkerRun implements WorkflowRun { private hostStarted = 0 /** Live children by callId; an entry leaves ONLY after its dispose settles (quiescence = empty). */ private readonly children = new Map() + /** In-flight child disposals by callId — the memo that gives every path (worker RPC, dispose(), reap) ONE shared disposal per child. */ + private readonly childDisposals = new Map>() private readonly quiescenceWaiters: (() => void)[] = [] /** The per-run abort fanout every child start request carries. */ private readonly controller = new AbortController() @@ -156,17 +163,24 @@ export class WorkerRun implements WorkflowRun { } /** - * Cancel + bounded settle + termination. Waits (at most the grace) for the - * result and child quiescence, then terminates the worker unconditionally - * — the thread never outlives its run — and reaps whatever children - * remain (their disposal is contained, not awaited past the grace, the - * same abandonment the seam documents for a slow-disposing child). - * Idempotent; safe on every path. + * Cancel + bounded settle + termination. Host-drives every registered + * child's disposal IMMEDIATELY — a wedged worker can relay no dispose RPC, + * and deferring child teardown to the post-terminate reap would spend the + * whole grace waiting for a quiescence that cannot start, then return with + * the disposals still in flight — so child disposal overlaps the same + * grace the worker gets to settle (the worker's own dispose RPCs join the + * shared per-child disposal). Waits (at most the grace) for the result and + * child quiescence, then terminates the worker unconditionally — the + * thread never outlives its run — and reaps whatever children remain + * (their disposal is contained, not awaited past the grace, the same + * abandonment the seam documents for a slow-disposing child). Idempotent; + * safe on every path. * @returns resolves when the run's resources are released or abandoned. */ dispose(): Promise { this.disposed ??= (async () => { this.cancel('workflow disposed') + for (const [callId, run] of [...this.children]) void this.disposeChild(callId, run) await Promise.race([ (async () => { await this.result @@ -278,31 +292,47 @@ export class WorkerRun implements WorkflowRun { private onChildDispose(callId: number): void { const run = this.children.get(callId) - /* v8 ignore next 5 -- dispose RPC for an already-reaped child: only a worker-death race can produce it, not orderable in-process */ if (run === undefined) { - // Already reaped — the ack is still owed (the worker-side wrapper awaits it). + // Already disposed host-side (a dispose() drive or a death reap beat + // the RPC) — the ack is still owed (the worker-side wrapper awaits it). this.post(HostToWorkerType.ChildDisposed, { callId }) return } - void run.dispose().then( - () => { - this.finishChild(callId) - this.post(HostToWorkerType.ChildDisposed, { callId }) - }, - (error: unknown) => { - // The subagent seam's dispose() is not supposed to reject; a backend - // that does anyway must not wedge the script's finally (which awaits - // the ack) — ack and move on. - this.ctx.logger.warn(`workflow-workerthread: child dispose failed: ${renderThrown(error)}`) - this.finishChild(callId) - this.post(HostToWorkerType.ChildDisposed, { callId }) - }, - ) + // disposeChild never rejects (containment is inside), so the ack always follows. + void this.disposeChild(callId, run).then(() => { this.post(HostToWorkerType.ChildDisposed, { callId }) }) } - /** Drop a child from the registry, releasing quiescence waiters at zero. */ + /** + * Start (or join) one registered child's disposal; the registry entry + * leaves when it settles. Memoized per callId: the worker's dispose RPC, + * the dispose() host drive, and the reap can all land on the same child — + * the child's `dispose()` runs once and every caller awaits that one + * settlement. A rejection is contained (the subagent seam's dispose() is + * not supposed to reject, but a backend that does anyway must not break + * quiescence): logged, and the child still leaves the registry. + * @param callId - the child's registry key. + * @param run - the registered child (the caller looked it up). + * @returns resolves when the disposal settled either way; never rejects. + */ + private disposeChild(callId: number, run: SubagentRun): Promise { + let disposal = this.childDisposals.get(callId) + if (disposal === undefined) { + disposal = run.dispose().then( + () => { this.finishChild(callId) }, + (error: unknown) => { + this.ctx.logger.warn(`workflow-workerthread: child dispose failed: ${renderThrown(error)}`) + this.finishChild(callId) + }, + ) + this.childDisposals.set(callId, disposal) + } + return disposal + } + + /** Drop a child from the registry (and its disposal memo), releasing quiescence waiters at zero. */ private finishChild(callId: number): void { this.children.delete(callId) + this.childDisposals.delete(callId) if (this.children.size === 0) { for (const waiter of this.quiescenceWaiters.splice(0)) waiter() } @@ -319,13 +349,7 @@ export class WorkerRun implements WorkflowRun { this.controller.abort(this.cancelReason ?? reason) for (const [callId, run] of [...this.children]) { run.cancel(this.cancelReason ?? reason) - void run.dispose().then( - () => { this.finishChild(callId) }, - (error: unknown) => { - this.ctx.logger.warn(`workflow-workerthread: child dispose failed during reap: ${renderThrown(error)}`) - this.finishChild(callId) - }, - ) + void this.disposeChild(callId, run) } } diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index 378dd6ecf6..c1c26dcf0f 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -23,6 +23,7 @@ interface ControlledRun { settle(result: SubagentResult): void cancelled: string | undefined disposed: boolean + disposeCalls: number } /** @@ -45,7 +46,7 @@ class StubProvider implements SubagentProvider { start(request: SubagentStartRequest): SubagentRun { let settle!: (result: SubagentResult) => void const result = new Promise((resolve) => { settle = resolve }) - const controlled: ControlledRun = { request, settle, cancelled: undefined, disposed: false } + const controlled: ControlledRun = { request, settle, cancelled: undefined, disposed: false, disposeCalls: 0 } this.runs.push(controlled) const index = this.runs.length - 1 request.signal?.addEventListener('abort', () => { settle({ output: [], stopReason: 'aborted' }) }, { once: true }) @@ -61,6 +62,7 @@ class StubProvider implements SubagentProvider { settle({ output: [], stopReason: 'aborted' }) }, dispose: () => { + controlled.disposeCalls += 1 if (this.disposeDelayMs === 0) { controlled.disposed = true return Promise.resolve() @@ -537,6 +539,64 @@ describe('dsh-workflow-workerthread', () => { expect(result.stopReason).toBe('cancelled') await handle.dispose() }, 15_000) + + it('dispose() on a wedged worker host-drives child disposal inside the grace: it returns with the children DISPOSED, not with their teardown still in flight', async () => { + const { ctx, parent, provider } = await setup({ + manual: true, + disposeDelayMs: 40, + config: { provider: 'stub', maxConcurrentAgents: 8, disposeGraceMs: 400 }, + }) + const handle = ctx.workflows.start({ + // Same shape as the wedged-cancel test above: the child's start RPC + // reaches the host, then the script seizes its worker's loop, so the + // worker can relay NO dispose RPC — the host's own dispose() drive is + // the only thing that can start (and finish) this child's disposal + // before the grace runs out. + ...scripted(` + agent('wedged child') + for (let i = 0; i < 20; i++) await null + const end = Date.now() + 1500 + while (Date.now() < end) {} + return 'raced' + `), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + const before = Date.now() + await handle.dispose() + // Bounded by the grace (plus the terminate), never by the 1.5s spin. + expect(Date.now() - before).toBeLessThan(1200) + // Not a waitFor: dispose() resolving IS the quiescence claim — the slow + // child disposal must be complete, not merely started (before the + // host-driven drive, disposal only STARTED at the post-terminate reap, + // so dispose() returned with it still in flight). + expect(provider.runs[0]!.disposed).toBe(true) + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + }, 15_000) + + it('a live child disposed by the dispose() drive is disposed ONCE, and the worker\'s late dispose RPC still gets its ack (the script settles, not the grace)', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const handle = ctx.workflows.start({ + ...scripted(` + await agent('long child') + return 'unreachable' + `), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + const handleDispose = handle.dispose() + const result = await handle.result + // The script itself settled (the wrapper's own dispose RPC found the + // child already reaped host-side and was acked) — a missing ack would + // wedge the wrapper's finally until the 5s default grace force-settle. + expect(result.stopReason).toBe('cancelled') + expect(result.error).toContain('workflow disposed') + await handleDispose + expect(provider.runs[0]!.disposed).toBe(true) + // The memo: the host drive and the worker's RPC share one disposal. + expect(provider.runs[0]!.disposeCalls).toBe(1) + }) }) describe('worker death', () => { From 387f19c7f607f5e350e3ffd28ec2516b3a70c878 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:23:45 +0800 Subject: [PATCH 105/119] docs: regenerate the module graph for the ask-user merge --- docs/module-graph.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/module-graph.md b/docs/module-graph.md index 5ef8313b4e..5bee74fae6 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -124,7 +124,9 @@ flowchart TD pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session pkg_tools --> pkg_agent + pkg_tools --> pkg_code_runtime pkg_tools --> pkg_llm + pkg_tools --> pkg_session pkg_tools --> pkg_system_prompt pkg_compact_basic --> pkg_agent pkg_compact_basic --> pkg_compact @@ -224,6 +226,7 @@ flowchart TD pkg_acp_agent --> pkg_agent_core pkg_acp_agent --> pkg_app_boot pkg_acp_agent --> pkg_session_persistence_jsonl + pkg_acp_agent --> pkg_tools pkg_acp_agent --> pkg_user_interaction pkg_stdio_agent --> pkg_agent pkg_stdio_agent --> pkg_agent_core @@ -232,6 +235,7 @@ flowchart TD pkg_stdio_agent --> pkg_session pkg_stdio_agent --> pkg_session_persistence_jsonl pkg_stdio_agent --> pkg_tool_ask_user + pkg_stdio_agent --> pkg_tools pkg_stdio_agent --> pkg_user_interaction ``` @@ -263,7 +267,7 @@ flowchart TD | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) | | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) | | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt) | +| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) | @@ -288,5 +292,5 @@ flowchart TD | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) | | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | -| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`user-interaction`](../packages/ui/user-interaction) | -| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`user-interaction`](../packages/ui/user-interaction) | +| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | +| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | From 27f9c45e6a43dc13c52674e23b95e1bcbcddb6a8 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:38:49 +0800 Subject: [PATCH 106/119] docs: update budget --- scripts/doc-budgets.manifest.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 337fc57763..dd7f2c3e74 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,5 +1,5 @@ { - "AGENTS.md": 1691, + "AGENTS.md": 1693, "docs/AGENTS.md": 1315, "docs/architecture.md": 1640, "docs/cordis-primer.md": 550, @@ -7,5 +7,5 @@ "docs/testing.md": 800, "examples/AGENTS.md": 610, "packages/AGENTS.md": 450, - "packages/README.md": 610 + "packages/README.md": 632 } From f505776eee9b1d157086338e19bdd60699b804f5 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 22:04:52 +0800 Subject: [PATCH 107/119] fix: keep the program on the COMPLETED run_code card (agent review follow-up) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit put the fenced program only on the pending card — but an ACP tool_call_update's content REPLACES the card content (Zed truncates to the new list, crates/acp_thread update_fields), so the code vanished the moment the run completed and was effectively never visible. presentResult now re-carries the fenced program before the captured output via a shared fencedProgram helper; the completed card body is program + output, rendered by Zed as syntax-highlighted markdown behind the card disclosure. Goldens re-recorded (filtered this time: DSH_SNAPSHOT=record vitest -u -t mode-turn); unit test pins the two-block result content. --- .../snapshots/both-mode-turn/session.jsonl | 239 ++++++----- .../both-mode-turn/stdout.golden.jsonl | 43 +- .../snapshots/code-mode-turn/session.jsonl | 376 +++++++++--------- .../code-mode-turn/stdout.golden.jsonl | 104 ++--- packages/core/tools/src/code-mode.ts | 30 +- packages/core/tools/tests/code-mode.spec.ts | 13 +- 6 files changed, 422 insertions(+), 383 deletions(-) diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl index c7bf7c3eba..e3f28fa3c6 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl @@ -1,122 +1,117 @@ -{"type":"session","version":0,"id":"14b611ba-2cfd-46d6-bdcb-4f12a261f651","createdAt":1783600817605,"cwd":"/tmp/acp-snap-cwd-f5yZEg"} -{"type":"turn/start","seq":0,"time":1783600817609,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783600817610,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783600817612,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783600817613,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-f5yZEg.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783600818106,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783600818107,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783600818317,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783600818345,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783600818346,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783600818346,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783600818347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} -{"type":"assistant/chunk","seq":11,"time":1783600818347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":12,"time":1783600818347,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} -{"type":"assistant/chunk","seq":13,"time":1783600818374,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":14,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":15,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":16,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":17,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" runs"}}} -{"type":"assistant/chunk","seq":18,"time":1783600818375,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":19,"time":1783600818407,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":20,"time":1783600818407,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} -{"type":"assistant/chunk","seq":21,"time":1783600818407,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} -{"type":"assistant/chunk","seq":22,"time":1783600818408,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":23,"time":1783600818432,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} -{"type":"assistant/chunk","seq":24,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" via"}}} -{"type":"assistant/chunk","seq":25,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} -{"type":"assistant/chunk","seq":26,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} -{"type":"assistant/chunk","seq":27,"time":1783600818433,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} -{"type":"assistant/chunk","seq":28,"time":1783600818434,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":29,"time":1783600818461,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} -{"type":"assistant/chunk","seq":30,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" its"}}} -{"type":"assistant/chunk","seq":31,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":32,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":33,"time":1783600818462,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} -{"type":"assistant/chunk","seq":34,"time":1783600818491,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":35,"time":1783600818491,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" do"}}} -{"type":"assistant/chunk","seq":36,"time":1783600818492,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":37,"time":1783600818492,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":38,"time":1783600818583,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":39,"time":1783600818583,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":40,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":41,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":42,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"code"}}} -{"type":"assistant/chunk","seq":43,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":44,"time":1783600818611,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":45,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":46,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":47,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" result"}}} -{"type":"assistant/chunk","seq":48,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":49,"time":1783600818643,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":50,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":51,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":52,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":53,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"({\\n"}}} -{"type":"assistant/chunk","seq":54,"time":1783600818670,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" "}}} -{"type":"assistant/chunk","seq":55,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":56,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":57,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":58,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":59,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" B"}}} -{"type":"assistant/chunk","seq":60,"time":1783600818698,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"OTH"}}} -{"type":"assistant/chunk","seq":61,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":62,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\\\",\\n"}}} -{"type":"assistant/chunk","seq":63,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" "}}} -{"type":"assistant/chunk","seq":64,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":65,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":66,"time":1783600818728,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":67,"time":1783600818757,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":68,"time":1783600818785,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":69,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" B"}}} -{"type":"assistant/chunk","seq":70,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"OTH"}}} -{"type":"assistant/chunk","seq":71,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":72,"time":1783600818786,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" string"}}} -{"type":"assistant/chunk","seq":73,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\\\"\\n"}}} -{"type":"assistant/chunk","seq":74,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"});\\n"}}} -{"type":"assistant/chunk","seq":75,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":76,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":" result"}}} -{"type":"assistant/chunk","seq":77,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":";"}}} -{"type":"assistant/chunk","seq":78,"time":1783600818815,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":79,"time":1783600818845,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":80,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns its output. Let me do that."}}}} -{"type":"assistant/chunk","seq":81,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK string\\\"\\n});\\nreturn result;\"}"}}}} -{"type":"assistant/chunk","seq":82,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3734,"outputTokens":107,"cacheReadTokens":0,"reasoningTokens":33}}}} -{"type":"assistant/chunk","seq":83,"time":1783600818906,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":84,"time":1783600818909,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call run_code with a program that runs `echo BOTH_OK` via tools.bash and returns its output. Let me do that."},{"type":"tool-call","id":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK string\\\"\\n});\\nreturn result;\"}"}],"usage":{"inputTokens":3734,"outputTokens":107,"cacheReadTokens":0,"reasoningTokens":33}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83],"surfaceOp":"append"} -{"type":"tool/call","seq":85,"time":1783600818909,"data":{"turn":1,"step":1,"callId":"call_00_Kv45KGQIqVt8nuaRebYh2326","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK string\\\"\\n});\\nreturn result;\"}"}} -{"type":"tool/code-dispatch","seq":86,"time":1783600819019,"data":{"parentCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326","subCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK string"},"isError":false,"resultSummary":"BOTH_OK\n"}} -{"type":"tool/result","seq":87,"time":1783600819021,"data":{"turn":1,"step":1,"callId":"call_00_Kv45KGQIqVt8nuaRebYh2326","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[85],"surfaceOp":"append"} -{"type":"step/end","seq":88,"time":1783600819022,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":89,"time":1783600819022,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":90,"time":1783600819418,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":91,"time":1783600819418,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":92,"time":1783600819515,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":93,"time":1783600819543,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} -{"type":"assistant/chunk","seq":94,"time":1783600819544,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":95,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} -{"type":"assistant/chunk","seq":96,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} -{"type":"assistant/chunk","seq":97,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":98,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} -{"type":"assistant/chunk","seq":99,"time":1783600819574,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} -{"type":"assistant/chunk","seq":100,"time":1783600819575,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} -{"type":"assistant/chunk","seq":101,"time":1783600819602,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":102,"time":1783600819603,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":103,"time":1783600819603,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":104,"time":1783600819603,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":105,"time":1783600819634,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":106,"time":1783600819635,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} -{"type":"assistant/chunk","seq":107,"time":1783600819635,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":108,"time":1783600819664,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} -{"type":"assistant/chunk","seq":109,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":110,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":111,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} -{"type":"assistant/chunk","seq":112,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} -{"type":"assistant/chunk","seq":113,"time":1783600819665,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} -{"type":"assistant/chunk","seq":114,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is \"BOTH_OK\". I need to reply with that output only and stop."}}}} -{"type":"assistant/chunk","seq":115,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} -{"type":"assistant/chunk","seq":116,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3840,"reasoningTokens":19}}}} -{"type":"assistant/chunk","seq":117,"time":1783600819693,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":118,"time":1783600819694,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is \"BOTH_OK\". I need to reply with that output only and stop."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":17,"outputTokens":23,"cacheReadTokens":3840,"reasoningTokens":19}},"sourceEventSeqs":[90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117],"surfaceOp":"append"} -{"type":"step/end","seq":119,"time":1783600819694,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":120,"time":1783600819694,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"7354d242-c6f9-4c36-9040-54c1fb295a6c","createdAt":1783604835700,"cwd":"/tmp/acp-snap-cwd-JyIozV"} +{"type":"turn/start","seq":0,"time":1783604835703,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783604835704,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783604835706,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783604835707,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JyIozV.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783604836078,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783604836079,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} +{"type":"assistant/chunk","seq":6,"time":1783604836174,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":7,"time":1783604836203,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":8,"time":1783604836204,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":9,"time":1783604836204,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" simple"}}} +{"type":"assistant/chunk","seq":10,"time":1783604836233,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Type"}}} +{"type":"assistant/chunk","seq":11,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Script"}}} +{"type":"assistant/chunk","seq":12,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":13,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":14,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" calls"}}} +{"type":"assistant/chunk","seq":15,"time":1783604836262,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} +{"type":"assistant/chunk","seq":16,"time":1783604836291,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} +{"type":"assistant/chunk","seq":17,"time":1783604836292,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} +{"type":"assistant/chunk","seq":18,"time":1783604836292,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":19,"time":1783604836321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":20,"time":1783604836321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":21,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":22,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} +{"type":"assistant/chunk","seq":23,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":24,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":25,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":26,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":27,"time":1783604836382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} +{"type":"assistant/chunk","seq":28,"time":1783604836383,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":29,"time":1783604836437,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":30,"time":1783604836437,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":31,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":32,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":33,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":34,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":35,"time":1783604836527,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":36,"time":1783604836528,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":37,"time":1783604836528,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":38,"time":1783604836528,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":39,"time":1783604836556,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":40,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" result"}}} +{"type":"assistant/chunk","seq":41,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":42,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":43,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":44,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":45,"time":1783604836602,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":46,"time":1783604836602,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"({\\n"}}} +{"type":"assistant/chunk","seq":47,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" "}}} +{"type":"assistant/chunk","seq":48,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":49,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":50,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":51,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":52,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":53,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":54,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":55,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\\\",\\n"}}} +{"type":"assistant/chunk","seq":56,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" "}}} +{"type":"assistant/chunk","seq":57,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":58,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":59,"time":1783604836674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":60,"time":1783604836675,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":61,"time":1783604836703,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":62,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":63,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":64,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":65,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" message"}}} +{"type":"assistant/chunk","seq":66,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\\\",\\n"}}} +{"type":"assistant/chunk","seq":67,"time":1783604836732,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"});\\n"}}} +{"type":"assistant/chunk","seq":68,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":69,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" result"}}} +{"type":"assistant/chunk","seq":70,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":";\\n"}}} +{"type":"assistant/chunk","seq":71,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":72,"time":1783604836762,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":73,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Let me write a simple TypeScript program that calls tools.bash to run `echo BOTH_OK` and returns the output."}}}} +{"type":"assistant/chunk","seq":74,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK message\\\",\\n});\\nreturn result;\\n\"}"}}}} +{"type":"assistant/chunk","seq":75,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3734,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":26}}}} +{"type":"assistant/chunk","seq":76,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":77,"time":1783604836825,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"Let me write a simple TypeScript program that calls tools.bash to run `echo BOTH_OK` and returns the output."},{"type":"tool-call","id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK message\\\",\\n});\\nreturn result;\\n\"}"}],"usage":{"inputTokens":3734,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":26}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76],"surfaceOp":"append"} +{"type":"tool/call","seq":78,"time":1783604836825,"data":{"turn":1,"step":1,"callId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK message\\\",\\n});\\nreturn result;\\n\"}"}} +{"type":"tool/code-dispatch","seq":79,"time":1783604836929,"data":{"parentCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","subCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK message"},"isError":false,"resultSummary":"BOTH_OK\n"}} +{"type":"tool/result","seq":80,"time":1783604836932,"data":{"turn":1,"step":1,"callId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[78],"surfaceOp":"append"} +{"type":"step/end","seq":81,"time":1783604836932,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":82,"time":1783604836933,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":83,"time":1783604837401,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":84,"time":1783604837401,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":85,"time":1783604837526,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" result"}}} +{"type":"assistant/chunk","seq":86,"time":1783604837554,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":87,"time":1783604837555,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":88,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} +{"type":"assistant/chunk","seq":89,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":90,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":91,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":92,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}} +{"type":"assistant/chunk","seq":93,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":94,"time":1783604837612,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}} +{"type":"assistant/chunk","seq":95,"time":1783604837612,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":96,"time":1783604837613,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":97,"time":1783604837613,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":98,"time":1783604837641,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":99,"time":1783604837643,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":100,"time":1783604837643,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":101,"time":1783604837643,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} +{"type":"assistant/chunk","seq":102,"time":1783604837644,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":103,"time":1783604837670,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} +{"type":"assistant/chunk","seq":104,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":105,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":106,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} +{"type":"assistant/chunk","seq":107,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} +{"type":"assistant/chunk","seq":108,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} +{"type":"assistant/chunk","seq":109,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The result is \"BOTH_OK\". The user asked me to reply with that output only and stop."}}}} +{"type":"assistant/chunk","seq":110,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} +{"type":"assistant/chunk","seq":111,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":139,"outputTokens":25,"cacheReadTokens":3712,"reasoningTokens":21}}}} +{"type":"assistant/chunk","seq":112,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":113,"time":1783604837702,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The result is \"BOTH_OK\". The user asked me to reply with that output only and stop."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":139,"outputTokens":25,"cacheReadTokens":3712,"reasoningTokens":21}},"sourceEventSeqs":[83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112],"surfaceOp":"append"} +{"type":"step/end","seq":114,"time":1783604837702,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":115,"time":1783604837702,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl index 4a959143d7..d5a8135569 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl @@ -1,50 +1,45 @@ {"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}}"}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" call"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" simple"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Type"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Script"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" runs"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" calls"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".b"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" B"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OTH"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" via"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".b"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" do"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK string\"\n});\nreturn result;","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK string\"\n});\nreturn result;\n```"}}]}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Kv45KGQIqVt8nuaRebYh2326","status":"completed","content":[{"type":"content","content":{"type":"text","text":"BOTH_OK\n"}}],"title":"Run code (1 tool call)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK message\",\n});\nreturn result;\n","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK message\",\n});\nreturn result;\n\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK message\",\n});\nreturn result;\n\n```"}}],"title":"Run code (1 tool call)"}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" result"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"B"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"OTH"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" asked"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl index 97d73709fc..69cf7d1825 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl @@ -1,181 +1,195 @@ -{"type":"session","version":0,"id":"9423eeec-62a7-46ea-8b05-abd52ac1e703","createdAt":1783600811133,"cwd":"/tmp/acp-snap-cwd-bdz41V"} -{"type":"turn/start","seq":0,"time":1783600811137,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783600811138,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783600811141,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783600811141,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-bdz41V.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783600811872,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783600811872,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783600812033,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783600812066,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} -{"type":"assistant/chunk","seq":11,"time":1783600812067,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":12,"time":1783600812068,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} -{"type":"assistant/chunk","seq":13,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} -{"type":"assistant/chunk","seq":14,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}} -{"type":"assistant/chunk","seq":15,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":16,"time":1783600812091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":17,"time":1783600812121,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":18,"time":1783600812121,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":19,"time":1783600812121,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} -{"type":"assistant/chunk","seq":20,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":21,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} -{"type":"assistant/chunk","seq":22,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":23,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":24,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":25,"time":1783600812151,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":26,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} -{"type":"assistant/chunk","seq":27,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} -{"type":"assistant/chunk","seq":28,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`,"}}} -{"type":"assistant/chunk","seq":29,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" then"}}} -{"type":"assistant/chunk","seq":30,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}} -{"type":"assistant/chunk","seq":31,"time":1783600812179,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":32,"time":1783600812208,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} -{"type":"assistant/chunk","seq":33,"time":1783600812208,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} -{"type":"assistant/chunk","seq":34,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} -{"type":"assistant/chunk","seq":35,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":36,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":37,"time":1783600812209,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} -{"type":"assistant/chunk","seq":38,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} -{"type":"assistant/chunk","seq":39,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":40,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} -{"type":"assistant/chunk","seq":41,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":42,"time":1783600812238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} -{"type":"assistant/chunk","seq":43,"time":1783600812267,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":44,"time":1783600812267,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} -{"type":"assistant/chunk","seq":45,"time":1783600812267,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":46,"time":1783600812296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} -{"type":"assistant/chunk","seq":47,"time":1783600812296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":48,"time":1783600812296,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":49,"time":1783600812388,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":50,"time":1783600812389,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":51,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":52,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":53,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"code"}}} -{"type":"assistant/chunk","seq":54,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":55,"time":1783600812418,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":56,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":57,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":58,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":59,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"1"}}} -{"type":"assistant/chunk","seq":60,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":61,"time":1783600812448,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":62,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":63,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":64,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":65,"time":1783600812479,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":66,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":67,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":68,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":69,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":70,"time":1783600812506,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":71,"time":1783600812507,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"_"}}} -{"type":"assistant/chunk","seq":72,"time":1783600812536,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"ONE"}}} -{"type":"assistant/chunk","seq":73,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":74,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":75,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":76,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":77,"time":1783600812537,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":78,"time":1783600812566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":79,"time":1783600812566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" first"}}} -{"type":"assistant/chunk","seq":80,"time":1783600812566,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" code"}}} -{"type":"assistant/chunk","seq":81,"time":1783600812595,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":82,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" });\\n"}}} -{"type":"assistant/chunk","seq":83,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":84,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":85,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"2"}}} -{"type":"assistant/chunk","seq":86,"time":1783600812596,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":87,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":88,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":89,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":90,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":91,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":92,"time":1783600812628,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":93,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":94,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":95,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":96,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":97,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"_T"}}} -{"type":"assistant/chunk","seq":98,"time":1783600812656,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"WO"}}} -{"type":"assistant/chunk","seq":99,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":100,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":101,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":102,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":103,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":104,"time":1783600812686,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":105,"time":1783600812714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" second"}}} -{"type":"assistant/chunk","seq":106,"time":1783600812714,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" code"}}} -{"type":"assistant/chunk","seq":107,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":108,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" });\\n"}}} -{"type":"assistant/chunk","seq":109,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":110,"time":1783600812715,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":111,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"1"}}} -{"type":"assistant/chunk","seq":112,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".trim"}}} -{"type":"assistant/chunk","seq":113,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"()"}}} -{"type":"assistant/chunk","seq":114,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" +"}}} -{"type":"assistant/chunk","seq":115,"time":1783600812744,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" \\\"+"}}} -{"type":"assistant/chunk","seq":116,"time":1783600812772,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":117,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" +"}}} -{"type":"assistant/chunk","seq":118,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":119,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"2"}}} -{"type":"assistant/chunk","seq":120,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":".trim"}}} -{"type":"assistant/chunk","seq":121,"time":1783600812773,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"();"}}} -{"type":"assistant/chunk","seq":122,"time":1783600812802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":123,"time":1783600812802,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":124,"time":1783600812863,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call the bash tool twice with `echo CODE_ONE` and `echo CODE_TWO`, then return the two outputs joined with a plus sign. Let me write a single run_code program."}}}} -{"type":"assistant/chunk","seq":125,"time":1783600812863,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo first code\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo second code\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}} -{"type":"assistant/chunk","seq":126,"time":1783600812864,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2121,"outputTokens":152,"cacheReadTokens":0,"reasoningTokens":44}}}} -{"type":"assistant/chunk","seq":127,"time":1783600812864,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":128,"time":1783600812866,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call the bash tool twice with `echo CODE_ONE` and `echo CODE_TWO`, then return the two outputs joined with a plus sign. Let me write a single run_code program."},{"type":"tool-call","id":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo first code\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo second code\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"usage":{"inputTokens":2121,"outputTokens":152,"cacheReadTokens":0,"reasoningTokens":44}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127],"surfaceOp":"append"} -{"type":"tool/call","seq":129,"time":1783600812866,"data":{"turn":1,"step":1,"callId":"call_00_RJaLT7yuWS9RqjyD9wP85417","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo first code\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo second code\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}} -{"type":"tool/code-dispatch","seq":130,"time":1783600812976,"data":{"parentCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","subCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo first code"},"isError":false,"resultSummary":"CODE_ONE\n"}} -{"type":"tool/code-dispatch","seq":131,"time":1783600812986,"data":{"parentCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","subCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo second code"},"isError":false,"resultSummary":"CODE_TWO\n"}} -{"type":"tool/result","seq":132,"time":1783600812988,"data":{"turn":1,"step":1,"callId":"call_00_RJaLT7yuWS9RqjyD9wP85417","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[129],"surfaceOp":"append"} -{"type":"step/end","seq":133,"time":1783600812989,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":134,"time":1783600812989,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":135,"time":1783600813658,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":136,"time":1783600813658,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":137,"time":1783600813840,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":138,"time":1783600813843,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" returned"}}} -{"type":"assistant/chunk","seq":139,"time":1783600813843,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":140,"time":1783600813871,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} -{"type":"assistant/chunk","seq":141,"time":1783600813900,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} -{"type":"assistant/chunk","seq":142,"time":1783600813929,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} -{"type":"assistant/chunk","seq":143,"time":1783600813929,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} -{"type":"assistant/chunk","seq":144,"time":1783600813929,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":145,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} -{"type":"assistant/chunk","seq":146,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} -{"type":"assistant/chunk","seq":147,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":148,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} -{"type":"assistant/chunk","seq":149,"time":1783600813958,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} -{"type":"assistant/chunk","seq":150,"time":1783600813959,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} -{"type":"assistant/chunk","seq":151,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} -{"type":"assistant/chunk","seq":152,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"`."}}} -{"type":"assistant/chunk","seq":153,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} -{"type":"assistant/chunk","seq":154,"time":1783600813987,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" need"}}} -{"type":"assistant/chunk","seq":155,"time":1783600814016,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":156,"time":1783600814017,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":157,"time":1783600814017,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":158,"time":1783600814017,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":159,"time":1783600814045,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} -{"type":"assistant/chunk","seq":160,"time":1783600814045,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} -{"type":"assistant/chunk","seq":161,"time":1783600814046,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} -{"type":"assistant/chunk","seq":162,"time":1783600814046,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":163,"time":1783600814131,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} -{"type":"assistant/chunk","seq":164,"time":1783600814131,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":165,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":166,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} -{"type":"assistant/chunk","seq":167,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} -{"type":"assistant/chunk","seq":168,"time":1783600814132,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} -{"type":"assistant/chunk","seq":169,"time":1783600814136,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} -{"type":"assistant/chunk","seq":170,"time":1783600814136,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} -{"type":"assistant/chunk","seq":171,"time":1783600814136,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} -{"type":"assistant/chunk","seq":172,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} -{"type":"assistant/chunk","seq":173,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The program returned exactly what was requested: `CODE_ONE+CODE_TWO`. I need to reply with that joined string only and stop."}}}} -{"type":"assistant/chunk","seq":174,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} -{"type":"assistant/chunk","seq":175,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":116,"outputTokens":37,"cacheReadTokens":2176,"reasoningTokens":29}}}} -{"type":"assistant/chunk","seq":176,"time":1783600814137,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":177,"time":1783600814137,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The program returned exactly what was requested: `CODE_ONE+CODE_TWO`. I need to reply with that joined string only and stop."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":116,"outputTokens":37,"cacheReadTokens":2176,"reasoningTokens":29}},"sourceEventSeqs":[135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176],"surfaceOp":"append"} -{"type":"step/end","seq":178,"time":1783600814137,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":179,"time":1783600814138,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"80586ac0-3af1-4291-aef4-908d65fd3585","createdAt":1783604829168,"cwd":"/tmp/acp-snap-cwd-7XHEGB"} +{"type":"turn/start","seq":0,"time":1783604829173,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783604829174,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783604829176,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783604829176,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-7XHEGB.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783604829821,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783604829821,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783604829991,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783604830022,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783604830022,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783604830022,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783604830023,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":11,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":12,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":13,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":14,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":15,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":16,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":17,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}} +{"type":"assistant/chunk","seq":18,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}} +{"type":"assistant/chunk","seq":19,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":20,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} +{"type":"assistant/chunk","seq":21,"time":1783604830109,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} +{"type":"assistant/chunk","seq":22,"time":1783604830109,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} +{"type":"assistant/chunk","seq":23,"time":1783604830138,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":24,"time":1783604830139,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":25,"time":1783604830167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":26,"time":1783604830167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":27,"time":1783604830167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":28,"time":1783604830168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":29,"time":1783604830168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":30,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} +{"type":"assistant/chunk","seq":31,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}} +{"type":"assistant/chunk","seq":32,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":33,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} +{"type":"assistant/chunk","seq":34,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} +{"type":"assistant/chunk","seq":35,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} +{"type":"assistant/chunk","seq":36,"time":1783604830216,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":37,"time":1783604830226,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} +{"type":"assistant/chunk","seq":38,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":39,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":40,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":41,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":42,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":43,"time":1783604830257,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} +{"type":"assistant/chunk","seq":44,"time":1783604830258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}} +{"type":"assistant/chunk","seq":45,"time":1783604830258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":46,"time":1783604830258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Jo"}}} +{"type":"assistant/chunk","seq":47,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ins"}}} +{"type":"assistant/chunk","seq":48,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":49,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} +{"type":"assistant/chunk","seq":50,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} +{"type":"assistant/chunk","seq":51,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":52,"time":1783604830290,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":53,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} +{"type":"assistant/chunk","seq":54,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} +{"type":"assistant/chunk","seq":55,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}} +{"type":"assistant/chunk","seq":56,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"4"}}} +{"type":"assistant/chunk","seq":57,"time":1783604830321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":58,"time":1783604830321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Returns"}}} +{"type":"assistant/chunk","seq":59,"time":1783604830348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":60,"time":1783604830348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} +{"type":"assistant/chunk","seq":61,"time":1783604830348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} +{"type":"assistant/chunk","seq":62,"time":1783604830377,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}} +{"type":"assistant/chunk","seq":63,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} +{"type":"assistant/chunk","seq":64,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":65,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":66,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}} +{"type":"assistant/chunk","seq":67,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":68,"time":1783604830466,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":69,"time":1783604830467,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":70,"time":1783604830496,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":71,"time":1783604830497,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":72,"time":1783604830497,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":73,"time":1783604830497,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":74,"time":1783604830525,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":75,"time":1783604830526,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":76,"time":1783604830526,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":77,"time":1783604830526,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":78,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":79,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":80,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":81,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":82,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":83,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":84,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":85,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":86,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":87,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":88,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":89,"time":1783604830585,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":90,"time":1783604830613,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":91,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":92,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":93,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":94,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":95,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":96,"time":1783604830646,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":97,"time":1783604830646,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":98,"time":1783604830673,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":99,"time":1783604830673,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":100,"time":1783604830673,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":101,"time":1783604830674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":102,"time":1783604830674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":103,"time":1783604830674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":104,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":105,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":106,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":107,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":108,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":109,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":110,"time":1783604830735,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":111,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":112,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":113,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":114,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":115,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":116,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":117,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":118,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":119,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":120,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":121,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":122,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":123,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":124,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":125,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":126,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":127,"time":1783604830791,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":128,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":129,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":130,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":131,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":132,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":133,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":134,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"()"}}} +{"type":"assistant/chunk","seq":135,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":136,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\"+"}}} +{"type":"assistant/chunk","seq":137,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":138,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":139,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} +{"type":"assistant/chunk","seq":140,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":141,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":142,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"();"}}} +{"type":"assistant/chunk","seq":143,"time":1783604830921,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":144,"time":1783604830922,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":145,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool to run `echo CODE_ONE`\n2. Calls bash tool to run `echo CODE_TWO`\n3. Joins the two outputs with a plus sign\n4. Returns that joined string\n\nLet me write this."}}}} +{"type":"assistant/chunk","seq":146,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}} +{"type":"assistant/chunk","seq":147,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2122,"outputTokens":173,"cacheReadTokens":0,"reasoningTokens":63}}}} +{"type":"assistant/chunk","seq":148,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":149,"time":1783604830977,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool to run `echo CODE_ONE`\n2. Calls bash tool to run `echo CODE_TWO`\n3. Joins the two outputs with a plus sign\n4. Returns that joined string\n\nLet me write this."},{"type":"tool-call","id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"usage":{"inputTokens":2122,"outputTokens":173,"cacheReadTokens":0,"reasoningTokens":63}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148],"surfaceOp":"append"} +{"type":"tool/call","seq":150,"time":1783604830977,"data":{"turn":1,"step":1,"callId":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}} +{"type":"tool/code-dispatch","seq":151,"time":1783604831079,"data":{"parentCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","subCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo CODE_ONE"},"isError":false,"resultSummary":"CODE_ONE\n"}} +{"type":"tool/code-dispatch","seq":152,"time":1783604831089,"data":{"parentCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","subCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo CODE_TWO"},"isError":false,"resultSummary":"CODE_TWO\n"}} +{"type":"tool/result","seq":153,"time":1783604831093,"data":{"turn":1,"step":1,"callId":"call_00_EvAw7ZWOeySn2jCErZPo6450","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[150],"surfaceOp":"append"} +{"type":"step/end","seq":154,"time":1783604831093,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":155,"time":1783604831094,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":156,"time":1783604831685,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":157,"time":1783604831685,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":158,"time":1783604831830,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":159,"time":1783604831859,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":160,"time":1783604831859,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":161,"time":1783604831859,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} +{"type":"assistant/chunk","seq":162,"time":1783604831890,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} +{"type":"assistant/chunk","seq":163,"time":1783604831890,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} +{"type":"assistant/chunk","seq":164,"time":1783604831890,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} +{"type":"assistant/chunk","seq":165,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":166,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":167,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":168,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} +{"type":"assistant/chunk","seq":169,"time":1783604831921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":170,"time":1783604831921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":171,"time":1783604831945,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":172,"time":1783604831945,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":173,"time":1783604831946,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} +{"type":"assistant/chunk","seq":174,"time":1783604831946,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"'ll"}}} +{"type":"assistant/chunk","seq":175,"time":1783604831974,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":176,"time":1783604831974,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":177,"time":1783604832003,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":178,"time":1783604832003,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":179,"time":1783604832004,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":180,"time":1783604832004,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":181,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} +{"type":"assistant/chunk","seq":182,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":183,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} +{"type":"assistant/chunk","seq":184,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":185,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} +{"type":"assistant/chunk","seq":186,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} +{"type":"assistant/chunk","seq":187,"time":1783604832068,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is exactly what was requested: CODE_ONE+CODE_TWO. I'll reply with that."}}}} +{"type":"assistant/chunk","seq":188,"time":1783604832069,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} +{"type":"assistant/chunk","seq":189,"time":1783604832069,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":138,"outputTokens":30,"cacheReadTokens":2176,"reasoningTokens":22}}}} +{"type":"assistant/chunk","seq":190,"time":1783604832069,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":191,"time":1783604832069,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is exactly what was requested: CODE_ONE+CODE_TWO. I'll reply with that."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":138,"outputTokens":30,"cacheReadTokens":2176,"reasoningTokens":22}},"sourceEventSeqs":[156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190],"surfaceOp":"append"} +{"type":"step/end","seq":192,"time":1783604832069,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":193,"time":1783604832069,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl index 916f20126c..ef6a5502a5 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl @@ -5,75 +5,87 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" call"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" twice"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`,"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" then"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" outputs"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" plus"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sign"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo first code\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo second code\" });\nreturn out1.trim() + \"+\" + out2.trim();","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo first code\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo second code\" });\nreturn out1.trim() + \"+\" + out2.trim();\n```"}}]}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_RJaLT7yuWS9RqjyD9wP85417","status":"completed","content":[{"type":"content","content":{"type":"text","text":"CODE_ONE+CODE_TWO"}}],"title":"Run code (2 tool calls)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Jo"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ins"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" outputs"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" plus"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sign"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Returns"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" this"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();\n```"}}],"title":"Run code (2 tool calls)"}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returned"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" was"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" requested"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"+"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'ll"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" joined"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" only"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_"}}}} diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index 1ae26a5eb9..0175e5811e 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -135,6 +135,15 @@ function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined { return m as unknown as RunCodeMeta } +/** + * Render a program as the markdown block the tool-call cards carry. + * @param code - the program text. + * @returns the ts-fenced markdown block. + */ +function fencedProgram(code: string): string { + return `\`\`\`ts\n${code}\n\`\`\`` +} + /** * Build the `run_code` {@link ToolDefinition}: one required `code` parameter, * executed through the dispatch bridge described in the module doc. The @@ -289,25 +298,32 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => exec.signal?.removeEventListener('abort', onOuterAbort) } }, - // The program IS the call: surface it as an always-visible fenced block in - // the card body (rawInput alone lands in detail/expanded views many - // clients never open). Fence collisions are impossible to break rendering - // — a backtick run inside the program at worst ends the block early. + // The program IS the call: surface it as a fenced block in the card body + // (rawInput alone lands in detail/expanded views many clients never + // open). Fence collisions are impossible to break rendering — a backtick + // run inside the program at worst ends the block early. presentCall: args => ({ card: 'generic', title: 'Run code', kind: 'execute', rawInput: args.code, - content: [{ type: 'text', text: `\`\`\`ts\n${args.code}\n\`\`\`` }], + content: [{ type: 'text', text: fencedProgram(args.code) }], }), - presentResult: (_args, result) => { + // The result re-carries the program BEFORE the captured output: an ACP + // tool_call_update's `content` REPLACES the pending card's (clients + // truncate to the new list), so a result without the program would wipe + // it the moment the run completes. + presentResult: (args, result) => { const meta = asRunCodeMeta(result.meta) if (!meta) return undefined const output = meta.logs.map(entry => entry.text).join('\n') return { card: 'generic', title: `Run code (${meta.dispatches} tool call${meta.dispatches === 1 ? '' : 's'})`, - ...output.length > 0 ? { content: [{ type: 'text', text: output }] } : {}, + content: [ + { type: 'text', text: fencedProgram(args.code) }, + ...output.length > 0 ? [{ type: 'text' as const, text: output }] : [], + ], } }, }) diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index 092e0ed90e..73e4ffc946 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -461,10 +461,17 @@ describe('the run_code dispatch bridge', () => { isError: false, meta: { logs: [{ source: 'console', level: 'log', text: 'printed' }], dispatches: 1 }, }) - expect(view).toEqual({ card: 'generic', title: 'Run code (1 tool call)', content: [{ type: 'text', text: 'printed' }] }) - // Plural title, and no content when the program printed nothing. + // The result re-carries the fenced program before the output: the ACP + // update's content REPLACES the pending card's, so omitting it would + // wipe the code from the card the moment the run completes. + expect(view).toEqual({ + card: 'generic', + title: 'Run code (1 tool call)', + content: [{ type: 'text', text: '```ts\nreturn 1\n```' }, { type: 'text', text: 'printed' }], + }) + // Plural title, and the program alone when it printed nothing. expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [], dispatches: 2 } })) - .toEqual({ card: 'generic', title: 'Run code (2 tool calls)' }) + .toEqual({ card: 'generic', title: 'Run code (2 tool calls)', content: [{ type: 'text', text: '```ts\nx\n```' }] }) // Replay with an unrecognizable meta falls back to the generic rendering. expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { other: true } })).toBeUndefined() expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false })).toBeUndefined() From fe4da9244f53cdbf66bcd9ce3cdaa6fc09dca362 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 22:12:30 +0800 Subject: [PATCH 108/119] fix(tool-cordis): validate a dynamic tool's execute return shape after the realm round-trip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sandbox execute wrapper JSON round-tripped the return and blindly cast it to ToolExecuteReturn. A JSON-valid but wrong-shape return — a bare string, { content: 'ok' }, blocks without a type tag — sailed through: the registry spreads result.content, so { content: 'ok' } became ['o','k'], passed the session log's isJsonValue gate, and the DeepSeek serializer then flattened it to '(no output)' — silent corruption of the next model request and every replay, instead of a contained tool error. The round-tripped value is now shape-checked against the two ToolExecuteReturn forms (array of content blocks, or { content: blocks, meta? }); block checks are structural only (plain object + string type tag) because the ContentBlock union is merge-extensible. A wrong shape — and the formerly cryptic forgot-return/bare-string cases — fails that one call with a teaching error echoing a truncated preview of what was returned and the two valid forms. New specs pin the object-form pass-through (meta included), six rejection shapes, and the preview truncation; per-file 100% coverage holds. --- ...6-07-08-self-referential-cordis-toolset.md | 2 +- packages/cordis/tool-cordis/src/guard.ts | 74 +++++++++++++-- .../cordis/tool-cordis/tests/mount.spec.ts | 89 +++++++++++++++++++ 3 files changed, 158 insertions(+), 7 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 8a43c271c3..3ec6c75cbc 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -30,7 +30,7 @@ Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. -Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, a read-only `tools.get`/`schemas`, `on`/`once`, `provide`, the timer helpers, and the services the plugin DECLARED in `inject`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code. Two narrower rules complete the surface. First, **service access requires an `inject` declaration**: reaching a service the mount did not declare is refused even when a global provider is live — otherwise a mount could depend on a provider cordis never sees, and unmounting that provider would neither park the consumer nor unwind the tools it registered, leaving a model-visible tool that fails only at execution time. Because the read is gated on the declaration, cross-mount `provide`/`inject` keeps its lifecycle guarantees (the plugin's own `inject` and the fiber's pending/active gating drive activation and unload); only the `apply`-time `ctx` surface is narrowed. Second, **`ctx.tools.get` returns a read-only schema view** (name/description/parameters), never the live `ToolDefinition` — handing back the definition would expose its `execute`, letting mount code call another tool directly and bypass `ToolRegistry.execute` and its pre/post-execute hooks and accounting; a mount that wants to invoke a tool must go through the registry, and one that wants to introspect gets the same view `schemas()` returns. +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores — and then shape-checks it against the two `ToolExecuteReturn` forms, so a JSON-valid but wrong-shape return (a bare string, `{ content: 'ok' }`) fails that one call with a teaching error instead of entering the log as corrupt tool-result content. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, a read-only `tools.get`/`schemas`, `on`/`once`, `provide`, the timer helpers, and the services the plugin DECLARED in `inject`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code. Two narrower rules complete the surface. First, **service access requires an `inject` declaration**: reaching a service the mount did not declare is refused even when a global provider is live — otherwise a mount could depend on a provider cordis never sees, and unmounting that provider would neither park the consumer nor unwind the tools it registered, leaving a model-visible tool that fails only at execution time. Because the read is gated on the declaration, cross-mount `provide`/`inject` keeps its lifecycle guarantees (the plugin's own `inject` and the fiber's pending/active gating drive activation and unload); only the `apply`-time `ctx` surface is narrowed. Second, **`ctx.tools.get` returns a read-only schema view** (name/description/parameters), never the live `ToolDefinition` — handing back the definition would expose its `execute`, letting mount code call another tool directly and bypass `ToolRegistry.execute` and its pre/post-execute hooks and accounting; a mount that wants to invoke a tool must go through the registry, and one that wants to introspect gets the same view `schemas()` returns. Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 90eaaec41b..f51faeb42e 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -27,8 +27,12 @@ * realm's `Object.prototype`, and the session log's append-time plainness check * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects * foreign-realm data — so every dynamic tool's `execute` return is JSON - * round-tripped into the host realm before it reaches the registry, and the - * schema itself is rebuilt as fresh host-realm objects. And a malformed tool + * round-tripped into the host realm and shape-checked against the two + * `ToolExecuteReturn` forms before it reaches the registry (the registry + * trusts the shape blindly — it spreads `result.content`, so an unvalidated + * `{ content: 'ok' }` would enter the session log as `['o','k']` and silently + * corrupt the next model request), and the schema itself is rebuilt as fresh + * host-realm objects. And a malformed tool * schema must fail at REGISTRATION, not when a later request assembles it — so * dynamic tool registration accepts only definitions produced by the sandbox's * `harness.defineTool`, which normalizes `parameters` up front. @@ -137,14 +141,67 @@ function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition } } +/** + * Structurally a content block, checked AFTER the JSON round-trip: a plain + * object carrying a string `type` tag. Deliberately nothing deeper — the + * ContentBlock union is merge-extensible (an unknown tag must pass), and every + * downstream consumer dispatches on `type` and falls through unknowns. + */ +function isContentBlockShape(value: unknown): boolean { + return isPlainRecord(value) && typeof value.type === 'string' +} + +/** + * How much of an invalid execute return the teaching error echoes back — a + * huge blob would burn the model turn the error is trying to save. + */ +const RETURN_PREVIEW_LIMIT = 120 + +/** + * Compact JSON preview of an invalid execute return for the teaching error + * (`String(…)` for the un-stringifiable undefined case), truncated to + * {@link RETURN_PREVIEW_LIMIT}. + */ +function describeReturn(value: unknown): string { + // JSON.stringify is TYPED as always returning string, but it yields + // undefined for an undefined input (the routed forgot-return case) — the + // assertion widens the type back to the runtime truth. + const json = JSON.stringify(value) as string | undefined + if (json === undefined) return String(value) + return json.length > RETURN_PREVIEW_LIMIT ? `${json.slice(0, RETURN_PREVIEW_LIMIT)}…` : json +} + +/** + * Validate a round-tripped `execute` return against the two shapes + * {@link ToolExecuteReturn} allows: an ARRAY of content blocks, or + * `{ content: blocks, meta? }`. The registry trusts the shape blindly — it + * spreads `result.content`, so an unvalidated `{ content: 'ok' }` would enter + * the session log as `['o','k']` and silently corrupt the next model request — + * so a wrong shape fails THIS call with a teaching error instead. + */ +function assertExecuteReturn(value: unknown): ToolExecuteReturn { + if (Array.isArray(value) && value.every(isContentBlockShape)) { + return value as ToolExecuteReturn + } + if (isPlainRecord(value) && Array.isArray(value.content) && value.content.every(isContentBlockShape)) { + return value as ToolExecuteReturn + } + throw new Error( + `execute returned ${describeReturn(value)} — a tool's execute must return an ARRAY of content blocks, never a bare string:\n` + + ' ✓ return [{ type: \'text\', text: someString }]\n' + + ' ✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }', + ) +} + /** * The `harness.defineTool` handed into the sandbox: the real DSL, with * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the * tool's `execute` return normalized into the host realm via a JSON round-trip - * (see the module doc). The round-trip also projects the return onto exactly - * what the log would durably store, so a non-JSON-serializable return surfaces - * as that one call's error instead of poisoning the turn. + * (see the module doc). The round-trip projects the return onto exactly what + * the log would durably store, and {@link assertExecuteReturn} then vets that + * projection — so a non-JSON-serializable OR wrong-shape return surfaces as + * that one call's teaching error instead of poisoning the turn. * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper. * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts. */ @@ -155,7 +212,12 @@ export function sandboxDefineTool(options: Parameters[0]): To return markDynamicTool({ ...tool, async execute(args, exec) { - return JSON.parse(JSON.stringify(await execute(args, exec))) as ToolExecuteReturn + // JSON.stringify yields NO JSON for an undefined (or function/symbol) + // return despite its string-typed signature — route that into + // assertExecuteReturn's teaching error rather than letting JSON.parse + // throw its cryptic '"undefined" is not valid JSON'. + const json = JSON.stringify(await execute(args, exec)) as string | undefined + return assertExecuteReturn(json === undefined ? undefined : JSON.parse(json) as unknown) }, }) } diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 7ee266ce30..fc29eeb2a0 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -60,6 +60,95 @@ describe('cordis_mount', () => { expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true) }) + it('threads the { content, meta } object return form through to the registry result', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'meta-return', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'meta_tool', + description: 'attaches a private presentation payload', + parameters: {}, + async execute() { + return { content: [{ type: 'text', text: 'ok' }], meta: { kind: 'demo' } } + }, + })) + }, + } + `, + }) + const result = await call(ctx, 'meta_tool', {}) + expect(result.isError).toBe(false) + expect(text(result)).toBe('ok') + expect(result.meta).toEqual({ kind: 'demo' }) + }) + + it.each([ + ['a bare string', 'return \'ok\'', '"ok"'], + ['an object whose content is a string', 'return { content: \'ok\' }', '{"content":"ok"}'], + ['an array of non-objects', 'return [\'ok\']', '["ok"]'], + ['blocks missing the type tag', 'return [{ text: \'hi\' }]', '[{"text":"hi"}]'], + ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', '{"content":[{"text":"hi"}]}'], + ['undefined — a forgotten return', 'return undefined', 'undefined'], + ])('rejects an execute return of %s as that one call\'s teaching error', async (_label, returnStatement, preview) => { + // The failure this prevents: the registry trusts the return shape + // (postExecute spreads result.content), so an unvalidated { content: 'ok' } + // would enter the session log as ['o','k'] and silently corrupt the next + // model request. The shape check turns it into THIS call's error instead — + // one well-formed text block the log and the model can digest. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'bad-return', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'bad_return_tool', + description: 'returns a wrong shape', + parameters: {}, + async execute() { ${returnStatement} }, + })) + }, + } + `, + }) + const result = await call(ctx, 'bad_return_tool', {}) + expect(result.isError).toBe(true) + expect(result.content).toHaveLength(1) + expect(result.content[0]!.type).toBe('text') + expect(text(result)).toContain(`execute returned ${preview}`) + expect(text(result)).toContain('must return an ARRAY of content blocks') + expect(text(result)).toContain('✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }') + }) + + it('truncates a huge invalid execute return in the teaching error', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'huge-return', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'huge_return_tool', + description: 'returns a huge wrong shape', + parameters: {}, + async execute() { return 'x'.repeat(500) }, + })) + }, + } + `, + }) + const result = await call(ctx, 'huge_return_tool', {}) + expect(result.isError).toBe(true) + expect(text(result)).toContain('…') + expect(text(result)).not.toContain('x'.repeat(200)) + }) + it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => { // The dialect models write by strong prior: the { type:'object', // properties, required: […] } wrapper, `type: 'integer'`, and From 30bc7f6a1d04783b4969b0b290f3246bb12ef6e9 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 9 Jul 2026 22:41:57 +0800 Subject: [PATCH 109/119] fix: the run_code program IS the execute-card title (root cause: Zed shows nothing else) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Systematic trace through Zed (crates/agent_ui thread_view.rs + crates/acp_thread): kind:execute routes a tool call onto the terminal-card layout, whose header (render_collapsible_command) has NO disclosure toggle, whose body content renders only when is_open — a flag only a real terminal entity can ever set — and which suppresses the Raw Input view outright. Every prior attempt (rawInput, pending content, completed content) targeted slots that layout structurally never renders; the one slot it always shows is the TITLE, which said "Run code". codex-acp confirms the idiom: execute cards are titled with the command itself. presentCall now titles the card with the program (rawInput kept as the canonical input slot); presentResult omits the title — an update replaces only provided fields, so the program header persists — and carries the captured output as content. Goldens re-recorded; the unit test pins title-carries-program on both frames. --- .../snapshots/both-mode-turn/session.jsonl | 233 +++++------ .../both-mode-turn/stdout.golden.jsonl | 44 +- .../snapshots/code-mode-turn/session.jsonl | 395 +++++++++--------- .../code-mode-turn/stdout.golden.jsonl | 51 ++- packages/core/tools/src/code-mode.ts | 38 +- packages/core/tools/tests/code-mode.spec.ts | 23 +- 6 files changed, 391 insertions(+), 393 deletions(-) diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl index e3f28fa3c6..afd1fa8e07 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl @@ -1,117 +1,116 @@ -{"type":"session","version":0,"id":"7354d242-c6f9-4c36-9040-54c1fb295a6c","createdAt":1783604835700,"cwd":"/tmp/acp-snap-cwd-JyIozV"} -{"type":"turn/start","seq":0,"time":1783604835703,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783604835704,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783604835706,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783604835707,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-JyIozV.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783604836078,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783604836079,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} -{"type":"assistant/chunk","seq":6,"time":1783604836174,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":7,"time":1783604836203,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} -{"type":"assistant/chunk","seq":8,"time":1783604836204,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":9,"time":1783604836204,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" simple"}}} -{"type":"assistant/chunk","seq":10,"time":1783604836233,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Type"}}} -{"type":"assistant/chunk","seq":11,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Script"}}} -{"type":"assistant/chunk","seq":12,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":13,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":14,"time":1783604836234,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" calls"}}} -{"type":"assistant/chunk","seq":15,"time":1783604836262,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}} -{"type":"assistant/chunk","seq":16,"time":1783604836291,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} -{"type":"assistant/chunk","seq":17,"time":1783604836292,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} -{"type":"assistant/chunk","seq":18,"time":1783604836292,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":19,"time":1783604836321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":20,"time":1783604836321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":21,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":22,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} -{"type":"assistant/chunk","seq":23,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} -{"type":"assistant/chunk","seq":24,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":25,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} -{"type":"assistant/chunk","seq":26,"time":1783604836350,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":27,"time":1783604836382,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" returns"}}} -{"type":"assistant/chunk","seq":28,"time":1783604836383,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":29,"time":1783604836437,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":30,"time":1783604836437,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":31,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":32,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":33,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":34,"time":1783604836499,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":35,"time":1783604836527,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"code"}}} -{"type":"assistant/chunk","seq":36,"time":1783604836528,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":37,"time":1783604836528,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":38,"time":1783604836528,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":39,"time":1783604836556,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":40,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" result"}}} -{"type":"assistant/chunk","seq":41,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":42,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":43,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":44,"time":1783604836557,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":45,"time":1783604836602,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":46,"time":1783604836602,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"({\\n"}}} -{"type":"assistant/chunk","seq":47,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" "}}} -{"type":"assistant/chunk","seq":48,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":49,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":50,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":51,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":52,"time":1783604836615,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" B"}}} -{"type":"assistant/chunk","seq":53,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"OTH"}}} -{"type":"assistant/chunk","seq":54,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":55,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\\\",\\n"}}} -{"type":"assistant/chunk","seq":56,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" "}}} -{"type":"assistant/chunk","seq":57,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":58,"time":1783604836644,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":59,"time":1783604836674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":60,"time":1783604836675,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":61,"time":1783604836703,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":62,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" B"}}} -{"type":"assistant/chunk","seq":63,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"OTH"}}} -{"type":"assistant/chunk","seq":64,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"_OK"}}} -{"type":"assistant/chunk","seq":65,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" message"}}} -{"type":"assistant/chunk","seq":66,"time":1783604836704,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\\\",\\n"}}} -{"type":"assistant/chunk","seq":67,"time":1783604836732,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"});\\n"}}} -{"type":"assistant/chunk","seq":68,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":69,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":" result"}}} -{"type":"assistant/chunk","seq":70,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":";\\n"}}} -{"type":"assistant/chunk","seq":71,"time":1783604836733,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":72,"time":1783604836762,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":73,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Let me write a simple TypeScript program that calls tools.bash to run `echo BOTH_OK` and returns the output."}}}} -{"type":"assistant/chunk","seq":74,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK message\\\",\\n});\\nreturn result;\\n\"}"}}}} -{"type":"assistant/chunk","seq":75,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3734,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":26}}}} -{"type":"assistant/chunk","seq":76,"time":1783604836823,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":77,"time":1783604836825,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"Let me write a simple TypeScript program that calls tools.bash to run `echo BOTH_OK` and returns the output."},{"type":"tool-call","id":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK message\\\",\\n});\\nreturn result;\\n\"}"}],"usage":{"inputTokens":3734,"outputTokens":101,"cacheReadTokens":0,"reasoningTokens":26}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76],"surfaceOp":"append"} -{"type":"tool/call","seq":78,"time":1783604836825,"data":{"turn":1,"step":1,"callId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({\\n command: \\\"echo BOTH_OK\\\",\\n description: \\\"Echo BOTH_OK message\\\",\\n});\\nreturn result;\\n\"}"}} -{"type":"tool/code-dispatch","seq":79,"time":1783604836929,"data":{"parentCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","subCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK message"},"isError":false,"resultSummary":"BOTH_OK\n"}} -{"type":"tool/result","seq":80,"time":1783604836932,"data":{"turn":1,"step":1,"callId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[78],"surfaceOp":"append"} -{"type":"step/end","seq":81,"time":1783604836932,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":82,"time":1783604836933,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":83,"time":1783604837401,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":84,"time":1783604837401,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":85,"time":1783604837526,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" result"}}} -{"type":"assistant/chunk","seq":86,"time":1783604837554,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} -{"type":"assistant/chunk","seq":87,"time":1783604837555,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} -{"type":"assistant/chunk","seq":88,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} -{"type":"assistant/chunk","seq":89,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} -{"type":"assistant/chunk","seq":90,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} -{"type":"assistant/chunk","seq":91,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} -{"type":"assistant/chunk","seq":92,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}} -{"type":"assistant/chunk","seq":93,"time":1783604837583,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":94,"time":1783604837612,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" asked"}}} -{"type":"assistant/chunk","seq":95,"time":1783604837612,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":96,"time":1783604837613,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":97,"time":1783604837613,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":98,"time":1783604837641,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":99,"time":1783604837643,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":100,"time":1783604837643,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":101,"time":1783604837643,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} -{"type":"assistant/chunk","seq":102,"time":1783604837644,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} -{"type":"assistant/chunk","seq":103,"time":1783604837670,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" stop"}}} -{"type":"assistant/chunk","seq":104,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":105,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":106,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} -{"type":"assistant/chunk","seq":107,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} -{"type":"assistant/chunk","seq":108,"time":1783604837671,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} -{"type":"assistant/chunk","seq":109,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The result is \"BOTH_OK\". The user asked me to reply with that output only and stop."}}}} -{"type":"assistant/chunk","seq":110,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} -{"type":"assistant/chunk","seq":111,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":139,"outputTokens":25,"cacheReadTokens":3712,"reasoningTokens":21}}}} -{"type":"assistant/chunk","seq":112,"time":1783604837701,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":113,"time":1783604837702,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The result is \"BOTH_OK\". The user asked me to reply with that output only and stop."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":139,"outputTokens":25,"cacheReadTokens":3712,"reasoningTokens":21}},"sourceEventSeqs":[83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112],"surfaceOp":"append"} -{"type":"step/end","seq":114,"time":1783604837702,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":115,"time":1783604837702,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"53db4e4d-46fb-444c-aba2-8809cf609f07","createdAt":1783607331385,"cwd":"/tmp/acp-snap-cwd-iMVFx2"} +{"type":"turn/start","seq":0,"time":1783607331389,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783607331390,"data":{"content":[{"type":"text","text":"Call the run_code tool (NOT the native bash tool directly) with a program that runs exactly `echo BOTH_OK` via tools.bash and returns its output. Then reply with that output only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783607331392,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783607331393,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-iMVFx2.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"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 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783607331860,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783607331860,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783607331943,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783607331972,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783607331972,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783607331972,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783607331973,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}} +{"type":"assistant/chunk","seq":11,"time":1783607331973,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":12,"time":1783607331973,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"run"}}} +{"type":"assistant/chunk","seq":13,"time":1783607332000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":14,"time":1783607332000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":15,"time":1783607332000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":16,"time":1783607332000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" call"}}} +{"type":"assistant/chunk","seq":17,"time":1783607332000,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":18,"time":1783607332026,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"tools"}}} +{"type":"assistant/chunk","seq":19,"time":1783607332026,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":".b"}}} +{"type":"assistant/chunk","seq":20,"time":1783607332026,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ash"}}} +{"type":"assistant/chunk","seq":21,"time":1783607332027,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":22,"time":1783607332027,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":23,"time":1783607332027,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":24,"time":1783607332055,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" command"}}} +{"type":"assistant/chunk","seq":25,"time":1783607332056,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":26,"time":1783607332056,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":27,"time":1783607332056,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" B"}}} +{"type":"assistant/chunk","seq":28,"time":1783607332056,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":29,"time":1783607332056,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":30,"time":1783607332081,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":31,"time":1783607332082,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":32,"time":1783607332082,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" return"}}} +{"type":"assistant/chunk","seq":33,"time":1783607332111,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" its"}}} +{"type":"assistant/chunk","seq":34,"time":1783607332111,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":35,"time":1783607332111,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":36,"time":1783607332232,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":37,"time":1783607332232,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":38,"time":1783607332232,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":39,"time":1783607332233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":40,"time":1783607332233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":41,"time":1783607332233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":42,"time":1783607332233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":43,"time":1783607332255,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":44,"time":1783607332255,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":45,"time":1783607332255,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" result"}}} +{"type":"assistant/chunk","seq":46,"time":1783607332283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":47,"time":1783607332283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":48,"time":1783607332283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":49,"time":1783607332283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":50,"time":1783607332283,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":51,"time":1783607332284,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":52,"time":1783607332312,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":53,"time":1783607332313,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":54,"time":1783607332313,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":55,"time":1783607332313,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":56,"time":1783607332313,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":57,"time":1783607332313,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":58,"time":1783607332339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":59,"time":1783607332339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":60,"time":1783607332339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":61,"time":1783607332339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":62,"time":1783607332339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":63,"time":1783607332339,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":64,"time":1783607332367,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":65,"time":1783607332367,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" B"}}} +{"type":"assistant/chunk","seq":66,"time":1783607332367,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"OTH"}}} +{"type":"assistant/chunk","seq":67,"time":1783607332367,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"_OK"}}} +{"type":"assistant/chunk","seq":68,"time":1783607332401,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":69,"time":1783607332402,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":70,"time":1783607332402,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":71,"time":1783607332402,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":" result"}}} +{"type":"assistant/chunk","seq":72,"time":1783607332430,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":";"}}} +{"type":"assistant/chunk","seq":73,"time":1783607332431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":74,"time":1783607332431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":75,"time":1783607332495,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use `run_code` to call `tools.bash` with the command `echo BOTH_OK` and return its output."}}}} +{"type":"assistant/chunk","seq":76,"time":1783607332495,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result;\"}"}}}} +{"type":"assistant/chunk","seq":77,"time":1783607332495,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3733,"outputTokens":102,"cacheReadTokens":0,"reasoningTokens":31}}}} +{"type":"assistant/chunk","seq":78,"time":1783607332495,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":79,"time":1783607332497,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use `run_code` to call `tools.bash` with the command `echo BOTH_OK` and return its output."},{"type":"tool-call","id":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result;\"}"}],"usage":{"inputTokens":3733,"outputTokens":102,"cacheReadTokens":0,"reasoningTokens":31}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78],"surfaceOp":"append"} +{"type":"tool/call","seq":80,"time":1783607332497,"data":{"turn":1,"step":1,"callId":"call_00_eZXVwOupAyCOXGgrtxXw7528","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Echo BOTH_OK\\\" });\\nreturn result;\"}"}} +{"type":"tool/code-dispatch","seq":81,"time":1783607332597,"data":{"parentCallId":"call_00_eZXVwOupAyCOXGgrtxXw7528","subCallId":"call_00_eZXVwOupAyCOXGgrtxXw7528:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Echo BOTH_OK"},"isError":false,"resultSummary":"BOTH_OK\n"}} +{"type":"tool/result","seq":82,"time":1783607332599,"data":{"turn":1,"step":1,"callId":"call_00_eZXVwOupAyCOXGgrtxXw7528","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false,"meta":{"logs":[],"dispatches":1}},"sourceEventSeqs":[80],"surfaceOp":"append"} +{"type":"step/end","seq":83,"time":1783607332599,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":84,"time":1783607332600,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":85,"time":1783607333261,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":86,"time":1783607333261,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":87,"time":1783607333471,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":88,"time":1783607333501,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":89,"time":1783607333501,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":90,"time":1783607333530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"B"}}} +{"type":"assistant/chunk","seq":91,"time":1783607333530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"OTH"}}} +{"type":"assistant/chunk","seq":92,"time":1783607333530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_OK"}}} +{"type":"assistant/chunk","seq":93,"time":1783607333530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":94,"time":1783607333530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" The"}}} +{"type":"assistant/chunk","seq":95,"time":1783607333530,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":96,"time":1783607333558,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" said"}}} +{"type":"assistant/chunk","seq":97,"time":1783607333587,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":98,"time":1783607333587,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":99,"time":1783607333587,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":100,"time":1783607333615,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":101,"time":1783607333616,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} +{"type":"assistant/chunk","seq":102,"time":1783607333616,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" only"}}} +{"type":"assistant/chunk","seq":103,"time":1783607333616,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":104,"time":1783607333616,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":105,"time":1783607333616,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"B"}}} +{"type":"assistant/chunk","seq":106,"time":1783607333644,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"OTH"}}} +{"type":"assistant/chunk","seq":107,"time":1783607333645,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_OK"}}} +{"type":"assistant/chunk","seq":108,"time":1783607333645,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is \"BOTH_OK\". The user said to reply with that output only."}}}} +{"type":"assistant/chunk","seq":109,"time":1783607333645,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"BOTH_OK"}}}} +{"type":"assistant/chunk","seq":110,"time":1783607333645,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":139,"outputTokens":22,"cacheReadTokens":3712,"reasoningTokens":18}}}} +{"type":"assistant/chunk","seq":111,"time":1783607333645,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":112,"time":1783607333646,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is \"BOTH_OK\". The user said to reply with that output only."},{"type":"text","text":"BOTH_OK"}],"usage":{"inputTokens":139,"outputTokens":22,"cacheReadTokens":3712,"reasoningTokens":18}},"sourceEventSeqs":[85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111],"surfaceOp":"append"} +{"type":"step/end","seq":113,"time":1783607333646,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":114,"time":1783607333646,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl index d5a8135569..41a2a751fe 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/stdout.golden.jsonl @@ -1,20 +1,25 @@ {"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}}"}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" simple"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Type"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Script"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" calls"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tools"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" use"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" call"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"tools"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".b"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ash"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" command"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" B"}}}} @@ -22,14 +27,14 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_OK"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" returns"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" return"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK message\",\n});\nreturn result;\n","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK message\",\n});\nreturn result;\n\n```"}}]}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_7FUi2qEmyE8bzRWZPbQI6485","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst result = await tools.bash({\n command: \"echo BOTH_OK\",\n description: \"Echo BOTH_OK message\",\n});\nreturn result;\n\n```"}}],"title":"Run code (1 tool call)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_eZXVwOupAyCOXGgrtxXw7528","title":"const result = await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });\nreturn result;","kind":"execute","status":"in_progress","rawInput":"const result = await tools.bash({ command: \"echo BOTH_OK\", description: \"Echo BOTH_OK\" });\nreturn result;"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_eZXVwOupAyCOXGgrtxXw7528","status":"completed","content":[{"type":"content","content":{"type":"text","text":"BOTH_OK\n"}}]}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" result"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"B"}}}} @@ -38,16 +43,13 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" The"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" asked"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" said"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" only"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" stop"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"B"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"OTH"}}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl index 69cf7d1825..acc807da41 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl @@ -1,195 +1,200 @@ -{"type":"session","version":0,"id":"80586ac0-3af1-4291-aef4-908d65fd3585","createdAt":1783604829168,"cwd":"/tmp/acp-snap-cwd-7XHEGB"} -{"type":"turn/start","seq":0,"time":1783604829173,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1783604829174,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"step/start","seq":2,"time":1783604829176,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":3,"time":1783604829176,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-7XHEGB.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} -{"type":"assistant/chunk","seq":4,"time":1783604829821,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":5,"time":1783604829821,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":6,"time":1783604829991,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} -{"type":"assistant/chunk","seq":7,"time":1783604830022,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} -{"type":"assistant/chunk","seq":8,"time":1783604830022,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":9,"time":1783604830022,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":10,"time":1783604830023,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} -{"type":"assistant/chunk","seq":11,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":12,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} -{"type":"assistant/chunk","seq":13,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":14,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} -{"type":"assistant/chunk","seq":15,"time":1783604830053,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} -{"type":"assistant/chunk","seq":16,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":17,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}} -{"type":"assistant/chunk","seq":18,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}} -{"type":"assistant/chunk","seq":19,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":20,"time":1783604830080,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} -{"type":"assistant/chunk","seq":21,"time":1783604830109,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} -{"type":"assistant/chunk","seq":22,"time":1783604830109,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} -{"type":"assistant/chunk","seq":23,"time":1783604830138,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":24,"time":1783604830139,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":25,"time":1783604830167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":26,"time":1783604830167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":27,"time":1783604830167,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":28,"time":1783604830168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} -{"type":"assistant/chunk","seq":29,"time":1783604830168,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":30,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} -{"type":"assistant/chunk","seq":31,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}} -{"type":"assistant/chunk","seq":32,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":33,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} -{"type":"assistant/chunk","seq":34,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" bash"}}} -{"type":"assistant/chunk","seq":35,"time":1783604830215,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tool"}}} -{"type":"assistant/chunk","seq":36,"time":1783604830216,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} -{"type":"assistant/chunk","seq":37,"time":1783604830226,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" run"}}} -{"type":"assistant/chunk","seq":38,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} -{"type":"assistant/chunk","seq":39,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} -{"type":"assistant/chunk","seq":40,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":41,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} -{"type":"assistant/chunk","seq":42,"time":1783604830227,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} -{"type":"assistant/chunk","seq":43,"time":1783604830257,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} -{"type":"assistant/chunk","seq":44,"time":1783604830258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}} -{"type":"assistant/chunk","seq":45,"time":1783604830258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":46,"time":1783604830258,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Jo"}}} -{"type":"assistant/chunk","seq":47,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ins"}}} -{"type":"assistant/chunk","seq":48,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} -{"type":"assistant/chunk","seq":49,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} -{"type":"assistant/chunk","seq":50,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} -{"type":"assistant/chunk","seq":51,"time":1783604830289,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":52,"time":1783604830290,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} -{"type":"assistant/chunk","seq":53,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} -{"type":"assistant/chunk","seq":54,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} -{"type":"assistant/chunk","seq":55,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}} -{"type":"assistant/chunk","seq":56,"time":1783604830320,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"4"}}} -{"type":"assistant/chunk","seq":57,"time":1783604830321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":58,"time":1783604830321,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Returns"}}} -{"type":"assistant/chunk","seq":59,"time":1783604830348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":60,"time":1783604830348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} -{"type":"assistant/chunk","seq":61,"time":1783604830348,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} -{"type":"assistant/chunk","seq":62,"time":1783604830377,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}} -{"type":"assistant/chunk","seq":63,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} -{"type":"assistant/chunk","seq":64,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} -{"type":"assistant/chunk","seq":65,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} -{"type":"assistant/chunk","seq":66,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" this"}}} -{"type":"assistant/chunk","seq":67,"time":1783604830378,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":68,"time":1783604830466,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":69,"time":1783604830467,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":70,"time":1783604830496,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"{"}}} -{"type":"assistant/chunk","seq":71,"time":1783604830497,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":72,"time":1783604830497,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"code"}}} -{"type":"assistant/chunk","seq":73,"time":1783604830497,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":74,"time":1783604830525,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":": "}}} -{"type":"assistant/chunk","seq":75,"time":1783604830526,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":76,"time":1783604830526,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":77,"time":1783604830526,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":78,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"1"}}} -{"type":"assistant/chunk","seq":79,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":80,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":81,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":82,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":83,"time":1783604830555,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":84,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":85,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":86,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":87,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":88,"time":1783604830584,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":89,"time":1783604830585,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":90,"time":1783604830613,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_"}}} -{"type":"assistant/chunk","seq":91,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ONE"}}} -{"type":"assistant/chunk","seq":92,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":93,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":94,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":95,"time":1783604830614,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":96,"time":1783604830646,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":97,"time":1783604830646,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":98,"time":1783604830673,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":99,"time":1783604830673,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_"}}} -{"type":"assistant/chunk","seq":100,"time":1783604830673,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ONE"}}} -{"type":"assistant/chunk","seq":101,"time":1783604830674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":102,"time":1783604830674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" });\\n"}}} -{"type":"assistant/chunk","seq":103,"time":1783604830674,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"const"}}} -{"type":"assistant/chunk","seq":104,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":105,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"2"}}} -{"type":"assistant/chunk","seq":106,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" ="}}} -{"type":"assistant/chunk","seq":107,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" await"}}} -{"type":"assistant/chunk","seq":108,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" tools"}}} -{"type":"assistant/chunk","seq":109,"time":1783604830705,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".b"}}} -{"type":"assistant/chunk","seq":110,"time":1783604830735,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"ash"}}} -{"type":"assistant/chunk","seq":111,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"({"}}} -{"type":"assistant/chunk","seq":112,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" command"}}} -{"type":"assistant/chunk","seq":113,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":114,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":115,"time":1783604830736,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"echo"}}} -{"type":"assistant/chunk","seq":116,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":117,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_T"}}} -{"type":"assistant/chunk","seq":118,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"WO"}}} -{"type":"assistant/chunk","seq":119,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\","}}} -{"type":"assistant/chunk","seq":120,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" description"}}} -{"type":"assistant/chunk","seq":121,"time":1783604830761,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":":"}}} -{"type":"assistant/chunk","seq":122,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\""}}} -{"type":"assistant/chunk","seq":123,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"E"}}} -{"type":"assistant/chunk","seq":124,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"cho"}}} -{"type":"assistant/chunk","seq":125,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" CODE"}}} -{"type":"assistant/chunk","seq":126,"time":1783604830790,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"_T"}}} -{"type":"assistant/chunk","seq":127,"time":1783604830791,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"WO"}}} -{"type":"assistant/chunk","seq":128,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":129,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" });\\n"}}} -{"type":"assistant/chunk","seq":130,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"return"}}} -{"type":"assistant/chunk","seq":131,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":132,"time":1783604830821,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"1"}}} -{"type":"assistant/chunk","seq":133,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".trim"}}} -{"type":"assistant/chunk","seq":134,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"()"}}} -{"type":"assistant/chunk","seq":135,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" +"}}} -{"type":"assistant/chunk","seq":136,"time":1783604830850,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" \\\"+"}}} -{"type":"assistant/chunk","seq":137,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\\\""}}} -{"type":"assistant/chunk","seq":138,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" +"}}} -{"type":"assistant/chunk","seq":139,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":" out"}}} -{"type":"assistant/chunk","seq":140,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"2"}}} -{"type":"assistant/chunk","seq":141,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":".trim"}}} -{"type":"assistant/chunk","seq":142,"time":1783604830882,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"();"}}} -{"type":"assistant/chunk","seq":143,"time":1783604830921,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"\""}}} -{"type":"assistant/chunk","seq":144,"time":1783604830922,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","argumentsDelta":"}"}}} -{"type":"assistant/chunk","seq":145,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool to run `echo CODE_ONE`\n2. Calls bash tool to run `echo CODE_TWO`\n3. Joins the two outputs with a plus sign\n4. Returns that joined string\n\nLet me write this."}}}} -{"type":"assistant/chunk","seq":146,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}}}} -{"type":"assistant/chunk","seq":147,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2122,"outputTokens":173,"cacheReadTokens":0,"reasoningTokens":63}}}} -{"type":"assistant/chunk","seq":148,"time":1783604830974,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":149,"time":1783604830977,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool to run `echo CODE_ONE`\n2. Calls bash tool to run `echo CODE_TWO`\n3. Joins the two outputs with a plus sign\n4. Returns that joined string\n\nLet me write this."},{"type":"tool-call","id":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}],"usage":{"inputTokens":2122,"outputTokens":173,"cacheReadTokens":0,"reasoningTokens":63}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148],"surfaceOp":"append"} -{"type":"tool/call","seq":150,"time":1783604830977,"data":{"turn":1,"step":1,"callId":"call_00_EvAw7ZWOeySn2jCErZPo6450","name":"run_code","arguments":"{\"code\": \"const out1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst out2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn out1.trim() + \\\"+\\\" + out2.trim();\"}"}} -{"type":"tool/code-dispatch","seq":151,"time":1783604831079,"data":{"parentCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","subCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo CODE_ONE"},"isError":false,"resultSummary":"CODE_ONE\n"}} -{"type":"tool/code-dispatch","seq":152,"time":1783604831089,"data":{"parentCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","subCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo CODE_TWO"},"isError":false,"resultSummary":"CODE_TWO\n"}} -{"type":"tool/result","seq":153,"time":1783604831093,"data":{"turn":1,"step":1,"callId":"call_00_EvAw7ZWOeySn2jCErZPo6450","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[150],"surfaceOp":"append"} -{"type":"step/end","seq":154,"time":1783604831093,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":155,"time":1783604831094,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":156,"time":1783604831685,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"assistant/chunk","seq":157,"time":1783604831685,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} -{"type":"assistant/chunk","seq":158,"time":1783604831830,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" output"}}} -{"type":"assistant/chunk","seq":159,"time":1783604831859,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} -{"type":"assistant/chunk","seq":160,"time":1783604831859,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} -{"type":"assistant/chunk","seq":161,"time":1783604831859,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} -{"type":"assistant/chunk","seq":162,"time":1783604831890,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} -{"type":"assistant/chunk","seq":163,"time":1783604831890,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} -{"type":"assistant/chunk","seq":164,"time":1783604831890,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} -{"type":"assistant/chunk","seq":165,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} -{"type":"assistant/chunk","seq":166,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} -{"type":"assistant/chunk","seq":167,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} -{"type":"assistant/chunk","seq":168,"time":1783604831920,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} -{"type":"assistant/chunk","seq":169,"time":1783604831921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} -{"type":"assistant/chunk","seq":170,"time":1783604831921,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} -{"type":"assistant/chunk","seq":171,"time":1783604831945,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} -{"type":"assistant/chunk","seq":172,"time":1783604831945,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":173,"time":1783604831946,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" I"}}} -{"type":"assistant/chunk","seq":174,"time":1783604831946,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"'ll"}}} -{"type":"assistant/chunk","seq":175,"time":1783604831974,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} -{"type":"assistant/chunk","seq":176,"time":1783604831974,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} -{"type":"assistant/chunk","seq":177,"time":1783604832003,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} -{"type":"assistant/chunk","seq":178,"time":1783604832003,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} -{"type":"assistant/chunk","seq":179,"time":1783604832004,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":180,"time":1783604832004,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} -{"type":"assistant/chunk","seq":181,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} -{"type":"assistant/chunk","seq":182,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} -{"type":"assistant/chunk","seq":183,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} -{"type":"assistant/chunk","seq":184,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} -{"type":"assistant/chunk","seq":185,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} -{"type":"assistant/chunk","seq":186,"time":1783604832032,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} -{"type":"assistant/chunk","seq":187,"time":1783604832068,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The output is exactly what was requested: CODE_ONE+CODE_TWO. I'll reply with that."}}}} -{"type":"assistant/chunk","seq":188,"time":1783604832069,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} -{"type":"assistant/chunk","seq":189,"time":1783604832069,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":138,"outputTokens":30,"cacheReadTokens":2176,"reasoningTokens":22}}}} -{"type":"assistant/chunk","seq":190,"time":1783604832069,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":191,"time":1783604832069,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The output is exactly what was requested: CODE_ONE+CODE_TWO. I'll reply with that."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":138,"outputTokens":30,"cacheReadTokens":2176,"reasoningTokens":22}},"sourceEventSeqs":[156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190],"surfaceOp":"append"} -{"type":"step/end","seq":192,"time":1783604832069,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":193,"time":1783604832069,"data":{"turn":1,"reason":{"kind":"completed"}}} +{"type":"session","version":0,"id":"687d082e-f208-45cb-a4e7-83235750c4a5","createdAt":1783607324790,"cwd":"/tmp/acp-snap-cwd-yWlMC5"} +{"type":"turn/start","seq":0,"time":1783607324794,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1783607324794,"data":{"content":[{"type":"text","text":"Using ONE run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO` — and return the two outputs joined with a plus sign. Then reply with that joined string only and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":1783607324797,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":1783607324797,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-yWlMC5.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.\n- A FAILED tool call rejects with an `Error` carrying the tool's error text — `try/catch` it to handle and continue.\n- Calls execute sequentially, even under `Promise.all`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ndeclare const tools: {\n /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. */\n bash(args: {\n /** The bash command to execute. */\n command: string;\n /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n description: string;\n /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n timeoutMs?: number;\n /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n workdir?: string;\n /** Run in the background and return a task id immediately. No timeout applies. */\n run_in_background?: boolean;\n }): Promise;\n /** Ask the executor to kill a running background bash task by task id. */\n bash_kill(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */\n bash_output(args: {\n /** Task id returned by the bash tool. */\n task_id: string;\n }): Promise;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit(args: {\n /** Path to edit, resolved by the filesystem backend. */\n file_path: string;\n /** Literal text to replace. Must match exactly. */\n old_string: string;\n /** Literal replacement text. Use an empty string to delete the match. */\n new_string: string;\n /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n replace_all?: boolean;\n }): Promise;\n /** Read a UTF-8 text file and return line-numbered content. */\n read(args: {\n /** Path to read, resolved by the filesystem backend. */\n file_path: string;\n /** 1-based first line to return. Defaults to 1. */\n offset?: number;\n /** Maximum number of lines to return. Defaults to 2000. */\n limit?: number;\n }): Promise;\n /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. */\n subagent(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n prompt: string;\n }): Promise;\n /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. */\n subagent_fork(args: {\n /** A short (3-5 word) description of the delegated task, for display. */\n description: string;\n /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n prompt: string;\n }): Promise;\n /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n todo_write(args: {\n /** The COMPLETE task list, replacing any previous list. */\n todos: ({\n /** What the task is — a short imperative line. */\n content: string;\n /** pending (not started) | in_progress (now) | completed (done). */\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n }): Promise;\n /** Create or fully replace a UTF-8 text file. */\n write(args: {\n /** Path to write, resolved by the filesystem backend. */\n file_path: string;\n /** Full UTF-8 text content to write. */\n content: string;\n }): Promise;\n}\n```","tools":[{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."}},"required":["code"]}}]},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":1783607325519,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":5,"time":1783607325519,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":6,"time":1783607325693,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} +{"type":"assistant/chunk","seq":7,"time":1783607325721,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}} +{"type":"assistant/chunk","seq":8,"time":1783607325722,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":9,"time":1783607325722,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}} +{"type":"assistant/chunk","seq":10,"time":1783607325722,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":11,"time":1783607325753,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":12,"time":1783607325753,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" single"}}} +{"type":"assistant/chunk","seq":13,"time":1783607325753,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":14,"time":1783607325779,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"run"}}} +{"type":"assistant/chunk","seq":15,"time":1783607325779,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_code"}}} +{"type":"assistant/chunk","seq":16,"time":1783607325779,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":17,"time":1783607325779,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" program"}}} +{"type":"assistant/chunk","seq":18,"time":1783607325779,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":19,"time":1783607325805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":":\n"}}} +{"type":"assistant/chunk","seq":20,"time":1783607325805,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"1"}}} +{"type":"assistant/chunk","seq":21,"time":1783607325806,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":22,"time":1783607325806,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Calls"}}} +{"type":"assistant/chunk","seq":23,"time":1783607325806,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":24,"time":1783607325833,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"bash"}}} +{"type":"assistant/chunk","seq":25,"time":1783607325834,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":26,"time":1783607325862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" twice"}}} +{"type":"assistant/chunk","seq":27,"time":1783607325862,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" -"}}} +{"type":"assistant/chunk","seq":28,"time":1783607325890,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" once"}}} +{"type":"assistant/chunk","seq":29,"time":1783607325890,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":30,"time":1783607325890,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":31,"time":1783607325891,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":32,"time":1783607325891,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":33,"time":1783607325891,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":34,"time":1783607325919,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":35,"time":1783607325919,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`"}}} +{"type":"assistant/chunk","seq":36,"time":1783607325919,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}} +{"type":"assistant/chunk","seq":37,"time":1783607325919,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" once"}}} +{"type":"assistant/chunk","seq":38,"time":1783607325919,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":39,"time":1783607325920,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" `"}}} +{"type":"assistant/chunk","seq":40,"time":1783607325948,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"echo"}}} +{"type":"assistant/chunk","seq":41,"time":1783607325948,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" CODE"}}} +{"type":"assistant/chunk","seq":42,"time":1783607325948,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":43,"time":1783607325948,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":44,"time":1783607325948,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"`\n"}}} +{"type":"assistant/chunk","seq":45,"time":1783607325948,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"2"}}} +{"type":"assistant/chunk","seq":46,"time":1783607325975,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":47,"time":1783607325975,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Jo"}}} +{"type":"assistant/chunk","seq":48,"time":1783607325975,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ins"}}} +{"type":"assistant/chunk","seq":49,"time":1783607325975,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":50,"time":1783607325976,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" two"}}} +{"type":"assistant/chunk","seq":51,"time":1783607325976,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" outputs"}}} +{"type":"assistant/chunk","seq":52,"time":1783607326003,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":53,"time":1783607326004,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" a"}}} +{"type":"assistant/chunk","seq":54,"time":1783607326004,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" plus"}}} +{"type":"assistant/chunk","seq":55,"time":1783607326004,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" sign"}}} +{"type":"assistant/chunk","seq":56,"time":1783607326004,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n"}}} +{"type":"assistant/chunk","seq":57,"time":1783607326004,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"3"}}} +{"type":"assistant/chunk","seq":58,"time":1783607326032,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":59,"time":1783607326032,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" Returns"}}} +{"type":"assistant/chunk","seq":60,"time":1783607326032,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":61,"time":1783607326060,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" joined"}}} +{"type":"assistant/chunk","seq":62,"time":1783607326060,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} +{"type":"assistant/chunk","seq":63,"time":1783607326091,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\n\n"}}} +{"type":"assistant/chunk","seq":64,"time":1783607326092,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"Let"}}} +{"type":"assistant/chunk","seq":65,"time":1783607326092,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":66,"time":1783607326092,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" write"}}} +{"type":"assistant/chunk","seq":67,"time":1783607326092,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}} +{"type":"assistant/chunk","seq":68,"time":1783607326092,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" code"}}} +{"type":"assistant/chunk","seq":69,"time":1783607326119,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":70,"time":1783607326176,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":71,"time":1783607326176,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":72,"time":1783607326203,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"{"}}} +{"type":"assistant/chunk","seq":73,"time":1783607326204,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":74,"time":1783607326204,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"code"}}} +{"type":"assistant/chunk","seq":75,"time":1783607326233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":76,"time":1783607326233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":": "}}} +{"type":"assistant/chunk","seq":77,"time":1783607326233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":78,"time":1783607326233,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":79,"time":1783607326260,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" r"}}} +{"type":"assistant/chunk","seq":80,"time":1783607326289,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":81,"time":1783607326289,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":82,"time":1783607326289,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":83,"time":1783607326289,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":84,"time":1783607326289,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":85,"time":1783607326290,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":86,"time":1783607326317,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":87,"time":1783607326318,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":88,"time":1783607326318,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":89,"time":1783607326318,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":90,"time":1783607326318,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":91,"time":1783607326318,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":92,"time":1783607326346,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":93,"time":1783607326346,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":94,"time":1783607326346,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":95,"time":1783607326346,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":96,"time":1783607326346,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":97,"time":1783607326346,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":98,"time":1783607326374,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":99,"time":1783607326405,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":100,"time":1783607326405,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":101,"time":1783607326405,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"_"}}} +{"type":"assistant/chunk","seq":102,"time":1783607326405,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"ONE"}}} +{"type":"assistant/chunk","seq":103,"time":1783607326431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":104,"time":1783607326431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":105,"time":1783607326431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"const"}}} +{"type":"assistant/chunk","seq":106,"time":1783607326431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" r"}}} +{"type":"assistant/chunk","seq":107,"time":1783607326431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":108,"time":1783607326431,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" ="}}} +{"type":"assistant/chunk","seq":109,"time":1783607326462,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" await"}}} +{"type":"assistant/chunk","seq":110,"time":1783607326462,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" tools"}}} +{"type":"assistant/chunk","seq":111,"time":1783607326462,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":".b"}}} +{"type":"assistant/chunk","seq":112,"time":1783607326462,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"ash"}}} +{"type":"assistant/chunk","seq":113,"time":1783607326462,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"({"}}} +{"type":"assistant/chunk","seq":114,"time":1783607326463,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" command"}}} +{"type":"assistant/chunk","seq":115,"time":1783607326487,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":116,"time":1783607326487,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":117,"time":1783607326487,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"echo"}}} +{"type":"assistant/chunk","seq":118,"time":1783607326488,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":119,"time":1783607326488,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":120,"time":1783607326488,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":121,"time":1783607326516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\\\","}}} +{"type":"assistant/chunk","seq":122,"time":1783607326516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" description"}}} +{"type":"assistant/chunk","seq":123,"time":1783607326516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":":"}}} +{"type":"assistant/chunk","seq":124,"time":1783607326516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" \\\""}}} +{"type":"assistant/chunk","seq":125,"time":1783607326516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"E"}}} +{"type":"assistant/chunk","seq":126,"time":1783607326516,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"cho"}}} +{"type":"assistant/chunk","seq":127,"time":1783607326543,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" CODE"}}} +{"type":"assistant/chunk","seq":128,"time":1783607326544,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"_T"}}} +{"type":"assistant/chunk","seq":129,"time":1783607326544,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"WO"}}} +{"type":"assistant/chunk","seq":130,"time":1783607326544,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":131,"time":1783607326544,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" });\\n"}}} +{"type":"assistant/chunk","seq":132,"time":1783607326544,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"return"}}} +{"type":"assistant/chunk","seq":133,"time":1783607326572,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" r"}}} +{"type":"assistant/chunk","seq":134,"time":1783607326572,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"1"}}} +{"type":"assistant/chunk","seq":135,"time":1783607326572,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":136,"time":1783607326600,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"()"}}} +{"type":"assistant/chunk","seq":137,"time":1783607326601,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":138,"time":1783607326601,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" \\\"+"}}} +{"type":"assistant/chunk","seq":139,"time":1783607326630,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\\\""}}} +{"type":"assistant/chunk","seq":140,"time":1783607326630,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" +"}}} +{"type":"assistant/chunk","seq":141,"time":1783607326630,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":" r"}}} +{"type":"assistant/chunk","seq":142,"time":1783607326630,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"2"}}} +{"type":"assistant/chunk","seq":143,"time":1783607326630,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":".trim"}}} +{"type":"assistant/chunk","seq":144,"time":1783607326630,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"();"}}} +{"type":"assistant/chunk","seq":145,"time":1783607326660,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"\""}}} +{"type":"assistant/chunk","seq":146,"time":1783607326660,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","argumentsDelta":"}"}}} +{"type":"assistant/chunk","seq":147,"time":1783607326724,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single `run_code` program that:\n1. Calls `bash` twice - once with `echo CODE_ONE` and once with `echo CODE_TWO`\n2. Joins the two outputs with a plus sign\n3. Returns that joined string\n\nLet me write the code."}}}} +{"type":"assistant/chunk","seq":148,"time":1783607326725,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","arguments":"{\"code\": \"const r1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst r2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn r1.trim() + \\\"+\\\" + r2.trim();\"}"}}}} +{"type":"assistant/chunk","seq":149,"time":1783607326725,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2122,"outputTokens":175,"cacheReadTokens":0,"reasoningTokens":65}}}} +{"type":"assistant/chunk","seq":150,"time":1783607326725,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":151,"time":1783607326727,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single `run_code` program that:\n1. Calls `bash` twice - once with `echo CODE_ONE` and once with `echo CODE_TWO`\n2. Joins the two outputs with a plus sign\n3. Returns that joined string\n\nLet me write the code."},{"type":"tool-call","id":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","arguments":"{\"code\": \"const r1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst r2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn r1.trim() + \\\"+\\\" + r2.trim();\"}"}],"usage":{"inputTokens":2122,"outputTokens":175,"cacheReadTokens":0,"reasoningTokens":65}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150],"surfaceOp":"append"} +{"type":"tool/call","seq":152,"time":1783607326727,"data":{"turn":1,"step":1,"callId":"call_00_Km1jhimv1ZVR4qbgjxAo9869","name":"run_code","arguments":"{\"code\": \"const r1 = await tools.bash({ command: \\\"echo CODE_ONE\\\", description: \\\"Echo CODE_ONE\\\" });\\nconst r2 = await tools.bash({ command: \\\"echo CODE_TWO\\\", description: \\\"Echo CODE_TWO\\\" });\\nreturn r1.trim() + \\\"+\\\" + r2.trim();\"}"}} +{"type":"tool/code-dispatch","seq":153,"time":1783607326846,"data":{"parentCallId":"call_00_Km1jhimv1ZVR4qbgjxAo9869","subCallId":"call_00_Km1jhimv1ZVR4qbgjxAo9869:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Echo CODE_ONE"},"isError":false,"resultSummary":"CODE_ONE\n"}} +{"type":"tool/code-dispatch","seq":154,"time":1783607326855,"data":{"parentCallId":"call_00_Km1jhimv1ZVR4qbgjxAo9869","subCallId":"call_00_Km1jhimv1ZVR4qbgjxAo9869:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Echo CODE_TWO"},"isError":false,"resultSummary":"CODE_TWO\n"}} +{"type":"tool/result","seq":155,"time":1783607326858,"data":{"turn":1,"step":1,"callId":"call_00_Km1jhimv1ZVR4qbgjxAo9869","content":[{"type":"text","text":"CODE_ONE+CODE_TWO"}],"isError":false,"meta":{"logs":[],"dispatches":2}},"sourceEventSeqs":[152],"surfaceOp":"append"} +{"type":"step/end","seq":156,"time":1783607326858,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":157,"time":1783607326859,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":158,"time":1783607327431,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"assistant/chunk","seq":159,"time":1783607327431,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} +{"type":"assistant/chunk","seq":160,"time":1783607327701,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" result"}}} +{"type":"assistant/chunk","seq":161,"time":1783607327725,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" is"}}} +{"type":"assistant/chunk","seq":162,"time":1783607327725,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}} +{"type":"assistant/chunk","seq":163,"time":1783607327725,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" what"}}} +{"type":"assistant/chunk","seq":164,"time":1783607327754,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" was"}}} +{"type":"assistant/chunk","seq":165,"time":1783607327754,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" requested"}}} +{"type":"assistant/chunk","seq":166,"time":1783607327754,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":":"}}} +{"type":"assistant/chunk","seq":167,"time":1783607327782,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}} +{"type":"assistant/chunk","seq":168,"time":1783607327783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":169,"time":1783607327783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_"}}} +{"type":"assistant/chunk","seq":170,"time":1783607327783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"ONE"}}} +{"type":"assistant/chunk","seq":171,"time":1783607327783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"+"}}} +{"type":"assistant/chunk","seq":172,"time":1783607327783,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"CODE"}}} +{"type":"assistant/chunk","seq":173,"time":1783607327811,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"_T"}}} +{"type":"assistant/chunk","seq":174,"time":1783607327812,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"WO"}}} +{"type":"assistant/chunk","seq":175,"time":1783607327812,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"\"."}}} +{"type":"assistant/chunk","seq":176,"time":1783607327812,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" Let"}}} +{"type":"assistant/chunk","seq":177,"time":1783607327812,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}} +{"type":"assistant/chunk","seq":178,"time":1783607327812,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}} +{"type":"assistant/chunk","seq":179,"time":1783607327839,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}} +{"type":"assistant/chunk","seq":180,"time":1783607327839,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" just"}}} +{"type":"assistant/chunk","seq":181,"time":1783607327868,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" that"}}} +{"type":"assistant/chunk","seq":182,"time":1783607327868,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":" string"}}} +{"type":"assistant/chunk","seq":183,"time":1783607327868,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}} +{"type":"assistant/chunk","seq":184,"time":1783607327868,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":185,"time":1783607327868,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":186,"time":1783607327868,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_"}}} +{"type":"assistant/chunk","seq":187,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":188,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"+"}}} +{"type":"assistant/chunk","seq":189,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"CODE"}}} +{"type":"assistant/chunk","seq":190,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"_T"}}} +{"type":"assistant/chunk","seq":191,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"WO"}}} +{"type":"assistant/chunk","seq":192,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The result is exactly what was requested: \"CODE_ONE+CODE_TWO\". Let me reply with just that string."}}}} +{"type":"assistant/chunk","seq":193,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}}} +{"type":"assistant/chunk","seq":194,"time":1783607327901,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":140,"outputTokens":33,"cacheReadTokens":2176,"reasoningTokens":25}}}} +{"type":"assistant/chunk","seq":195,"time":1783607327902,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":196,"time":1783607327902,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The result is exactly what was requested: \"CODE_ONE+CODE_TWO\". Let me reply with just that string."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"usage":{"inputTokens":140,"outputTokens":33,"cacheReadTokens":2176,"reasoningTokens":25}},"sourceEventSeqs":[158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195],"surfaceOp":"append"} +{"type":"step/end","seq":197,"time":1783607327902,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":198,"time":1783607327902,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl index ef6a5502a5..ff20b92fc5 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/stdout.golden.jsonl @@ -8,38 +8,39 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" single"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"run"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_code"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" program"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"bash"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" twice"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" -"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" once"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Calls"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" tool"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" run"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" and"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" once"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" `"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"echo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"`\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Jo"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ins"}}}} @@ -51,7 +52,7 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" plus"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" sign"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Returns"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} @@ -61,31 +62,35 @@ {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" write"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" this"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" code"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","title":"Run code","kind":"execute","status":"in_progress","rawInput":"const out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();\n```"}}]}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_EvAw7ZWOeySn2jCErZPo6450","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```ts\nconst out1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst out2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn out1.trim() + \"+\" + out2.trim();\n```"}}],"title":"Run code (2 tool calls)"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Km1jhimv1ZVR4qbgjxAo9869","title":"const r1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst r2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn r1.trim() + \"+\" + r2.trim();","kind":"execute","status":"in_progress","rawInput":"const r1 = await tools.bash({ command: \"echo CODE_ONE\", description: \"Echo CODE_ONE\" });\nconst r2 = await tools.bash({ command: \"echo CODE_TWO\", description: \"Echo CODE_TWO\" });\nreturn r1.trim() + \"+\" + r2.trim();"}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Km1jhimv1ZVR4qbgjxAo9869","status":"completed","content":[{"type":"content","content":{"type":"text","text":"CODE_ONE+CODE_TWO"}}]}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" output"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" result"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" is"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" exactly"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" what"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" was"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" requested"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" CODE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"+"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"_T"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WO"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} -{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"'ll"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" just"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" that"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" string"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CODE"}}}} {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"_"}}}} diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index 0175e5811e..a6ef7a271a 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -135,15 +135,6 @@ function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined { return m as unknown as RunCodeMeta } -/** - * Render a program as the markdown block the tool-call cards carry. - * @param code - the program text. - * @returns the ts-fenced markdown block. - */ -function fencedProgram(code: string): string { - return `\`\`\`ts\n${code}\n\`\`\`` -} - /** * Build the `run_code` {@link ToolDefinition}: one required `code` parameter, * executed through the dispatch bridge described in the module doc. The @@ -298,32 +289,29 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => exec.signal?.removeEventListener('abort', onOuterAbort) } }, - // The program IS the call: surface it as a fenced block in the card body - // (rawInput alone lands in detail/expanded views many clients never - // open). Fence collisions are impossible to break rendering — a backtick - // run inside the program at worst ends the block early. + // The program IS the title, the way command tools title their cards with + // the command: an execute-card's title is the one slot an ACP client + // always shows (Zed's execute cards render no body content and no raw + // input without a real terminal attached), so anywhere else the code + // would be invisible. Multi-line titles are the execute-card idiom — + // capable clients render them whole; others truncate to the first line + // and still hold the full program in rawInput. presentCall: args => ({ card: 'generic', - title: 'Run code', + title: args.code, kind: 'execute', rawInput: args.code, - content: [{ type: 'text', text: fencedProgram(args.code) }], }), - // The result re-carries the program BEFORE the captured output: an ACP - // tool_call_update's `content` REPLACES the pending card's (clients - // truncate to the new list), so a result without the program would wipe - // it the moment the run completes. - presentResult: (args, result) => { + // Title omitted on the result: an update replaces only the fields it + // carries, so the pending card's program title persists through + // completion; the captured output rides as body content. + presentResult: (_args, result) => { const meta = asRunCodeMeta(result.meta) if (!meta) return undefined const output = meta.logs.map(entry => entry.text).join('\n') return { card: 'generic', - title: `Run code (${meta.dispatches} tool call${meta.dispatches === 1 ? '' : 's'})`, - content: [ - { type: 'text', text: fencedProgram(args.code) }, - ...output.length > 0 ? [{ type: 'text' as const, text: output }] : [], - ], + ...output.length > 0 ? { content: [{ type: 'text' as const, text: output }] } : {}, } }, }) diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts index 73e4ffc946..f7f4b058d8 100644 --- a/packages/core/tools/tests/code-mode.spec.ts +++ b/packages/core/tools/tests/code-mode.spec.ts @@ -444,34 +444,33 @@ describe('the run_code dispatch bridge', () => { expect((result.content[0] as { text: string }).text).toContain('requires a code runtime') }) - it('presents the pending call as a generic execute card carrying the program, and the result with the captured output', async () => { + it('presents the PROGRAM as the execute-card title on both call and result (the one slot execute cards always show)', async () => { const { ctx } = await setup({ mode: 'code' }) const tool = ctx.tools.get(RUN_CODE_NAME)! + // The program IS the title, mirroring how command tools title their cards + // with the command: an ACP client's execute-card header is the only + // always-visible slot (Zed renders no body content and no raw input for + // execute-kind cards without a real terminal). expect(tool.presentCall?.({ code: 'return 1' })).toEqual({ card: 'generic', - title: 'Run code', + title: 'return 1', kind: 'execute', rawInput: 'return 1', - // The program rides the card BODY as a fenced block — visible in ACP - // clients that never open the rawInput detail view. - content: [{ type: 'text', text: '```ts\nreturn 1\n```' }], }) const view = tool.presentResult?.({ code: 'return 1' }, { content: [{ type: 'text', text: 'model-facing' }], isError: false, meta: { logs: [{ source: 'console', level: 'log', text: 'printed' }], dispatches: 1 }, }) - // The result re-carries the fenced program before the output: the ACP - // update's content REPLACES the pending card's, so omitting it would - // wipe the code from the card the moment the run completes. + // The result omits the title — an update replaces only provided fields, + // so the pending card's program title persists through completion. expect(view).toEqual({ card: 'generic', - title: 'Run code (1 tool call)', - content: [{ type: 'text', text: '```ts\nreturn 1\n```' }, { type: 'text', text: 'printed' }], + content: [{ type: 'text', text: 'printed' }], }) - // Plural title, and the program alone when it printed nothing. + // No captured output → no content either; everything pending persists. expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [], dispatches: 2 } })) - .toEqual({ card: 'generic', title: 'Run code (2 tool calls)', content: [{ type: 'text', text: '```ts\nx\n```' }] }) + .toEqual({ card: 'generic' }) // Replay with an unrecognizable meta falls back to the generic rendering. expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { other: true } })).toBeUndefined() expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false })).toBeUndefined() From 64d0703c408016999948fd3bafabf207e652ed01 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 23:05:43 +0800 Subject: [PATCH 110/119] workflow: host-guarantee the agent-start/agent-end pairing on every stop path agent-end was worker-authored only, so a start already forwarded to observers lost its paired end whenever the worker could no longer speak - the grace force-settle terminating a wedged script, or an unexpected worker death - stranding progress consumers with agents that never finish (ds-review-bot finding on #233). The host now keeps a ledger of forwarded starts and funnels every agent-end through one gate: worker-reported ends pair (and clear) their entry, and both termination paths drain the remainder as synthesized 'cancelled' ends BEFORE the run settles, so ends always precede workflow/end. A real settlement racing the force-settle loses to the synthesized cancellation - the same first-wins override onResult applies to the run's own result. --- docs/cordis-catalog/events.md | 6 +- docs/cordis-catalog/services.md | 2 +- .../workflow/workflow-workerthread/README.md | 2 +- .../workflow-workerthread/src/host.ts | 54 ++++++++- .../tests/workflow-workerthread.spec.ts | 106 ++++++++++++++++++ packages/workflow/workflow/src/index.ts | 5 +- 6 files changed, 164 insertions(+), 11 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 02e12359ac..28dc1f17f5 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -365,13 +365,13 @@ Source: [`packages/core/tools/src/index.ts:77`](../../packages/core/tools/src/in ### `workflow/agent-end` — emit -One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start']. +One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`. ```ts cordis-catalog 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void ``` -Source: [`packages/workflow/workflow/src/index.ts:93`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:96`](../../packages/workflow/workflow/src/index.ts) ### `workflow/agent-start` — emit @@ -391,7 +391,7 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void ``` -Source: [`packages/workflow/workflow/src/index.ts:103`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:106`](../../packages/workflow/workflow/src/index.ts) ### `workflow/log` — emit diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 493381d1c9..0622e56a60 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -276,7 +276,7 @@ Semantics every implementation must honor: abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Source: [`packages/workflow/workflow/src/index.ts:207`](../../packages/workflow/workflow/src/index.ts) +Source: [`packages/workflow/workflow/src/index.ts:210`](../../packages/workflow/workflow/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) diff --git a/packages/workflow/workflow-workerthread/README.md b/packages/workflow/workflow-workerthread/README.md index dc8859d351..2d98273ae0 100644 --- a/packages/workflow/workflow-workerthread/README.md +++ b/packages/workflow/workflow-workerthread/README.md @@ -32,7 +32,7 @@ Values LEAVING the script (hook options/schemas, the script's return) are materi Per-run limits: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` posts the cancel to the worker (its hooks start throwing `CANCELLED`; the script dies at its next await) and cancels every host-side child NOW on **both seam channels** — the shared request signal aborts AND each registered child's explicit `cancel()` is called host-side, because the seam leaves a provider free to honor either channel and a worker wedged in a synchronous spin could not relay its own per-child cancel RPCs (those later land as idempotent no-ops). The grace then arms: a run still unsettled `disposeGraceMs` later force-settles `cancelled` and the worker is **terminated**. A cancellation that lands before the body runs (the ready→go handshake) reports `cancelled` without executing anything; a worker `result` racing an in-flight host cancellation reports `cancelled` too (first-wins settlement — the seam-visible result had not settled when cancellation was requested); post-cancel `phase`/`log` narration is suppressed host-side, while cancelled children still deliver their paired `agent-end`. -A worker that dies unexpectedly (an OOM, a script reaching `process.exit` through the documented vm escape) settles the run `stopReason: 'error'` with the exit diagnostics — or `'cancelled'` when a cancel was in flight — and the host-side child registry is what winds every surviving child down. `dispose()` = cancel + immediate host-driven disposal of every registered child (a wedged worker can relay no dispose RPC, so child teardown overlaps the grace instead of starting after it; the worker's own dispose RPCs join the same per-child disposal) + bounded wait (result, then child-registry quiescence, capped by the grace) + unconditional `worker.terminate()`: the thread never outlives its run. Once a run settles, stray children a script fired without awaiting are cancelled too, and `dispose()` waits for their disposal (bounded by the grace) before returning. +A worker that dies unexpectedly (an OOM, a script reaching `process.exit` through the documented vm escape) settles the run `stopReason: 'error'` with the exit diagnostics — or `'cancelled'` when a cancel was in flight — and the host-side child registry is what winds every surviving child down. `dispose()` = cancel + immediate host-driven disposal of every registered child (a wedged worker can relay no dispose RPC, so child teardown overlaps the grace instead of starting after it; the worker's own dispose RPCs join the same per-child disposal) + bounded wait (result, then child-registry quiescence, capped by the grace) + unconditional `worker.terminate()`: the thread never outlives its run. Once a run settles, stray children a script fired without awaiting are cancelled too, and `dispose()` waits for their disposal (bounded by the grace) before returning. `agent-start`/`agent-end` pairing is host-guaranteed the same way: forwarded starts live in a ledger, worker-reported ends pair them on the graceful paths, and the termination paths (grace force-settle, worker death) synthesize the missing ends (outcome `cancelled`) before the run settles — a start still in flight across the force-settle can surface after `workflow/end`, immediately paired the same way. **Engine-specific limitations**: worker startup is paid per run; on a termination path `agentsStarted` reports the HOST-observed count (accepted `child-start`s — calls still queued worker-side for a concurrency slot are unknowable then); and a returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — with the value-boundary guard applying to the resolution. diff --git a/packages/workflow/workflow-workerthread/src/host.ts b/packages/workflow/workflow-workerthread/src/host.ts index c512c15dee..28db34f097 100644 --- a/packages/workflow/workflow-workerthread/src/host.ts +++ b/packages/workflow/workflow-workerthread/src/host.ts @@ -22,7 +22,11 @@ * survivor when the worker dies or is terminated mid-flight. The three * paths share ONE disposal per child (memoized by callId; the seam's * dispose() is idempotent anyway, the memo keeps the bookkeeping and the - * containment warn single). On a termination path `agentsStarted` reports the + * containment warn single). Lifecycle pairing is host-guaranteed the same + * way: every forwarded `agent-start` lives in a ledger, and a start the + * dead or terminated worker never paired is closed by a synthesized + * `agent-end` (outcome `'cancelled'`) before the run settles. On a + * termination path `agentsStarted` reports the * HOST-observed count (accepted `child-start` messages) — `agent()` calls * still queued worker-side for a concurrency slot are unknowable then; the * worker's own count rides the result message on every graceful path. @@ -37,7 +41,7 @@ import type { Context } from 'cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import { assertNever } from '@deepseek-ai/dsh-llm' import type { SubagentRun } from '@deepseek-ai/dsh-subagent' -import type { WorkflowMeta, WorkflowResult, WorkflowRun, WorkflowRunId } from '@deepseek-ai/dsh-workflow' +import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowMeta, WorkflowResult, WorkflowRun, WorkflowRunId } from '@deepseek-ai/dsh-workflow' import { renderThrown } from './realm.ts' import type { ExecutionObserver } from './runtime.ts' import { HostToWorkerType, WorkerToHostType } from './protocol.ts' @@ -92,6 +96,8 @@ export class WorkerRun implements WorkflowRun { private readonly children = new Map() /** In-flight child disposals by callId — the memo that gives every path (worker RPC, dispose(), reap) ONE shared disposal per child. */ private readonly childDisposals = new Map>() + /** Started-but-not-ended agents by seq — the pairing ledger the HOST guarantees (see {@link endAgent}). */ + private readonly liveAgents = new Map() private readonly quiescenceWaiters: (() => void)[] = [] /** The per-run abort fanout every child start request carries. */ private readonly controller = new AbortController() @@ -155,6 +161,10 @@ export class WorkerRun implements WorkflowRun { // ChildCancel relay (those later RPCs land as idempotent no-ops). for (const run of this.children.values()) run.cancel(this.cancelReason) this.graceTimer = setTimeout(() => { + // The worker may no longer speak (it is about to be terminated): pair + // every stranded start before the run settles, so ends precede + // workflow/end. + this.endStrandedAgents() this.settleResult(this.cancelledResult(this.hostStarted)) void this.worker.terminate() }, this.disposeGraceMs) @@ -225,13 +235,15 @@ export class WorkerRun implements WorkflowRun { if (this.cancelReason === undefined) this.observer.log(message.message) break case WorkerToHostType.AgentStart: + this.liveAgents.set(message.info.seq, message.info) this.observer.agentStart(message.info) break case WorkerToHostType.AgentEnd: // NOT suppressed on cancel: cancelled children report their paired - // agent-end with outcome 'cancelled' (the one-pair-per-started-child - // contract holds on every stop path). - this.observer.agentEnd(message.info) + // agent-end with outcome 'cancelled'. The gate (with the termination + // paths' synthesis) is what makes the one-pair-per-started-child + // contract hold on every stop path. + this.endAgent(message.info) break case WorkerToHostType.ChildStart: this.onChildStart(message.callId, message.request) @@ -373,6 +385,10 @@ export class WorkerRun implements WorkflowRun { private onWorkerDeath(message: string): void { // Whatever the worker left behind must not leak — abort + dispose it all. if (this.children.size > 0) this.reapChildren('workflow worker gone') + // The thread is gone: no more worker-authored agent-ends can arrive — + // pair every stranded start (a start that crossed between the grace + // force-settle and this exit included) before the run settles. + this.endStrandedAgents() // settleResult no-ops on an already-settled run (the expected exit after // a dispose's terminate lands here too). if (this.cancelReason !== undefined) { @@ -382,6 +398,34 @@ export class WorkerRun implements WorkflowRun { this.settleResult({ value: null, stopReason: 'error', error: message, agentsStarted: this.hostStarted }) } + /** + * The single agent-end emission gate: forwards `end` iff its start is still + * unpaired in the ledger, so every forwarded `workflow/agent-start` gets + * EXACTLY one `workflow/agent-end` — the worker's own report where it can + * speak, a host-synthesized one where it cannot ({@link endStrandedAgents}). + * @param end - the settlement to emit (worker-reported or synthesized). + */ + private endAgent(end: WorkflowAgentEndInfo): void { + /* v8 ignore next -- a real end still in flight across the grace force-settle: not orderable in-process */ + if (!this.liveAgents.delete(end.seq)) return + this.observer.agentEnd(end) + } + + /** + * Synthesize the missing `agent-end` for every started-but-unpaired agent, + * outcome `'cancelled'`: the reap cancels every child, and a real + * settlement racing the force-settle loses to the cancellation — the same + * first-wins override {@link onResult} applies to the run's own result. + * Called where the worker can no longer speak (the grace force-settle, + * worker death), BEFORE settleResult, so the paired ends reach observers + * before `workflow/end`. + */ + private endStrandedAgents(): void { + for (const info of [...this.liveAgents.values()]) { + this.endAgent({ ...info, outcome: 'cancelled' }) + } + } + private cancelledResult(agentsStarted: number): WorkflowResult { // cancel() is the only writer of cancelReason and every caller checks it // first; the fallback guards the type, not a reachable path. diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index c1c26dcf0f..eb50ec1121 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -597,6 +597,73 @@ describe('dsh-workflow-workerthread', () => { // The memo: the host drive and the worker's RPC share one disposal. expect(provider.runs[0]!.disposeCalls).toBe(1) }) + + it('the grace force-settle pairs every stranded start: a host-synthesized cancelled agent-end lands before workflow/end', async () => { + const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 8, disposeGraceMs: 300 } }) + const ends: { seq: number; outcome: string }[] = [] + const order: string[] = [] + ctx.on('workflow/agent-start', (_info, agent) => { order.push(`start:${agent.seq}`) }) + ctx.on('workflow/agent-end', (_info, agent) => { + ends.push({ seq: agent.seq, outcome: agent.outcome }) + order.push(`end:${agent.seq}`) + }) + ctx.on('workflow/end', () => { order.push('run-end') }) + const handle = ctx.workflows.start({ + // 'slow' starts and its agent-start crosses to observers (the awaited + // 'fast' call keeps the worker loop turning), then the script seizes + // the loop: the wedged worker can never author slow's agent-end — + // only the host's ledger can close the pair. + ...scripted(` + const p = agent('slow') + await agent('fast') + const end = Date.now() + 1500 + while (Date.now() < end) {} + return 'raced' + `), + parent, + }) + await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) + const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')! + fast.settle(text('fast done')) + handle.cancel('stop now') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + // fast's end is the worker's own report; slow's is host-synthesized at + // the force-settle — exactly one end per started seq, no third event. + expect(ends).toEqual([ + { seq: 2, outcome: 'completed' }, + { seq: 1, outcome: 'cancelled' }, + ]) + // Both ends reached observers BEFORE workflow/end: a progress consumer + // can finalize its state at run-end without dangling agents. + expect(order.indexOf('run-end')).toBe(order.length - 1) + await handle.dispose() + }, 15_000) + + it('graceful cancellation keeps pairing worker-authored: exactly one agent-end per start, nothing synthesized on top', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const ends: { seq: number; outcome: string }[] = [] + const order: string[] = [] + ctx.on('workflow/agent-end', (_info, agent) => { + ends.push({ seq: agent.seq, outcome: agent.outcome }) + order.push(`end:${agent.seq}`) + }) + ctx.on('workflow/end', () => { order.push('run-end') }) + const handle = ctx.workflows.start({ + ...scripted("await parallel([() => agent('a'), () => agent('b')])\nreturn 'unreachable'"), + parent, + }) + await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + handle.cancel('user stop') + const result = await handle.result + expect(result.stopReason).toBe('cancelled') + // The live worker reported both pairs itself; the ledger must not add + // a synthesized duplicate on any path that settles inside the grace. + expect(ends.map(end => end.outcome)).toEqual(['cancelled', 'cancelled']) + expect(new Set(ends.map(end => end.seq)).size).toBe(2) + expect(order.indexOf('run-end')).toBe(order.length - 1) + await handle.dispose() + }) }) describe('worker death', () => { @@ -669,6 +736,45 @@ describe('dsh-workflow-workerthread', () => { await handle.dispose() }, 15_000) + it('a worker death pairs every stranded start: the synthesized cancelled agent-end precedes the error workflow/end', async () => { + const { ctx, parent, provider } = await setup({ manual: true }) + const ends: { seq: number; outcome: string }[] = [] + const order: string[] = [] + ctx.on('workflow/agent-start', (_info, agent) => { order.push(`start:${agent.seq}`) }) + ctx.on('workflow/agent-end', (_info, agent) => { + ends.push({ seq: agent.seq, outcome: agent.outcome }) + order.push(`end:${agent.seq}`) + }) + ctx.on('workflow/end', () => { order.push('run-end') }) + const handle = ctx.workflows.start({ + // Same choreography as the force-settle pairing test, but the worker + // DIES (the documented vm escape) instead of being terminated: the + // exit path must close slow's pair from the ledger too. The escaped + // setTimeout lets the already-posted messages flush before the kill. + ...scripted(` + const p = agent('slow') + await agent('fast') + const proc = ${ESCAPE} + const st = globalThis.constructor.constructor('return setTimeout')() + await new Promise(resolve => st(resolve, 150)) + proc.exit(7) + `), + parent, + }) + await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) + const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')! + fast.settle(text('fast done')) + const result = await handle.result + expect(result.stopReason).toBe('error') + expect(result.error).toContain('exit code 7') + expect(ends).toEqual([ + { seq: 2, outcome: 'completed' }, + { seq: 1, outcome: 'cancelled' }, + ]) + expect(order.indexOf('run-end')).toBe(order.length - 1) + await handle.dispose() + }, 15_000) + it('a dispose ack racing the worker death is dropped, not crashed (post after exit)', async () => { // Slow child disposal: the ack resolves only AFTER the worker died, so // it has nowhere to go and must be dropped silently (the workerGone diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts index 6c2b797362..91caa314dc 100644 --- a/packages/workflow/workflow/src/index.ts +++ b/packages/workflow/workflow/src/index.ts @@ -85,7 +85,10 @@ declare module 'cordis' { 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void /** * One `agent()` call settled (clean result, child failure, or run - * cancellation). Paired with {@link Events['workflow/agent-start']}. + * cancellation). Paired with {@link Events['workflow/agent-start']} by + * `agent.seq`, exactly once per started call on every stop path — on an + * engine termination path (a worker killed past its grace) the end is + * engine-synthesized with outcome `'cancelled'`. * @param info - the run's identity snapshot. * @param agent - the call identity plus its outcome. * @mode emit From 7d3b16c1845ee10386df8577156ed841b94ccd8b Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 23:10:28 +0800 Subject: [PATCH 111/119] docs: update budget / catalog --- docs/event-producer-consumer.md | 4 ++-- scripts/doc-budgets.manifest.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index b266089b38..a677e2a24a 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -36,9 +36,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:113`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:77`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:93`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:96`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:85`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | -| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:103`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:106`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:77`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:62`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 49535f0efb..a5261698a2 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,7 +1,7 @@ { "AGENTS.md": 1802, "docs/AGENTS.md": 1315, - "docs/architecture.md": 1640, + "docs/architecture.md": 1642, "docs/cordis-primer.md": 550, "docs/defensive-patterns.md": 550, "docs/testing.md": 800, From bf1ab14b789e7efeeb1057eba042f1202b084de5 Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 9 Jul 2026 23:48:29 +0800 Subject: [PATCH 112/119] a human touch get some headroom --- docs/AGENTS.md | 7 ++++--- docs/architecture.md | 47 +++++++++++++++++++++++++------------------ docs/cordis-primer.md | 30 +++++++++++++-------------- 3 files changed, 46 insertions(+), 38 deletions(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 771e30dcc6..118c535874 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — The documentation standard -This file is the contract for every Markdown surface in the repo: each tier's job, the writing rules, and the word budgets the `verify-doc-budgets` gate enforces. The audit/apply workflow is the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill; the decision record is [the doc-tiers-and-budgets RFC](rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md). +This file is the contract for every Markdown files in the repo: each tier's job, the writing rules, and the word budgets that `verify-doc-budgets` enforces. The audit/apply workflow is the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill; the decision record is [the doc-tiers-and-budgets RFC](rfc/implemented/process/2026-07-04-doc-tiers-and-budgets.md). ## The tier taxonomy: one home per fact @@ -31,10 +31,11 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How - **Every new event's JSDoc carries an `@mode` tag** (emit | waterfall | parallel | serial); the catalog generator hard-errors without it. Write the JSDoc to stand alone — it becomes the catalog entry ([catalog RFC](rfc/implemented/process/2026-06-20-generated-cordis-catalog.md)). - **The [core-data-structures catalog](core-data-structures/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](core-data-structures/core.md#what-counts-as-core)). - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)). +- Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams". -## Budgets and the ceiling gate +## Wordcount Budgets -Standing docs accrete: every PR has a lesson it wants to append, and without displacement pressure nothing ever leaves. The gate is that pressure. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) lists the accretion-prone standing docs with a word ceiling each; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. +Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure, which lists the word count of each standing docs; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. - Ceilings are an enforcement frontier with working headroom: a ceiling sits at least 5% above the doc's current size — routine edits pass, real growth trips the gate — and ratchets down, keeping the margin, as the doc reaches target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600. - When the gate goes red, first ask whether the added words belong in this tier and whether the existing wording can be condensed. If the words do not belong, relocate per the taxonomy above; if they belong but can be shorter, condense. If they truly need the space, raise the ceiling and justify the manifest diff in the PR. A ceiling set too low is a budget bug, and correcting it is the fix. diff --git a/docs/architecture.md b/docs/architecture.md index 69e43a423f..c0e7bdac08 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,23 +1,23 @@ # DeepSeek Harness Architecture -The **DeepSeek Harness SDK** is an SDK for building agent harnesses on the Cordis framework. The governing principle is simple: **everything is a plugin**. The shipped agent loop is one plugin in the default bundle, not a privileged kernel. +The project is an SDK for building agent harnesses. The idea is to have **everything as a plugin**. For example, the agent loop is just one plugin shipped by default. -Read this page as the system map before changing `packages/`. It explains how the runtime is shaped, how the default loop moves work, where state lives, and where extensions attach. Type shapes live in [core-data-structures/](core-data-structures/core.md); exact event and service signatures live in the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs; package contracts live in the [package map](../packages/README.md); rationale lives in the [RFCs](rfc/README.md). New to Cordis? Start with the [Cordis primer](cordis-primer.md). +## Overview -## System Shape +The project is based on [Cordis](cordis-primer.md). -A running harness is one Cordis context. Packages contribute service keys, typed events, and disposable registrations to that context. Services are the stable call surfaces (`ctx.llm`, `ctx.tools`, `ctx.sessions`); events are interception and notification points (`agent/request`, `tools/pre-execute`, `session/event`); registrations install prompt sections, tool schemas, providers, adapters, and listeners. +A running harness is one Cordis context. Packages contribute service keys, typed events, and disposable registrations to that context. Services provides stable call signatures (`ctx.llm`, `ctx.tools`, `ctx.sessions`); events are interception and notification points (`agent/request`, `tools/pre-execute`, `session/event`); registrations install prompt sections, tool schemas, providers, adapters, and listeners. -The default distribution is a composition, not a hierarchy. `packages/core/` is a repository grouping for the default agent spine; capability seams around it are equally first-class plugins. +Composition is preferred over inheritance. `packages/core/` is a repository grouping for the default agent flow; capability around it are equally first-class plugins from a Cordis perspective. -### Default Service Spine +### Default Services | ctx key | Package | Role | |---|---|---| | `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions | | `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and prompt variables | | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) | -| `ctx.agents` | `dsh-agent` | live agent registry, public `Agent` handle, `agent/*` vocabulary | +| `ctx.agents` | `dsh-agent` | live agent registry, public `Agent` handle, `agent/*` events | | `ctx.agentLoop` | `dsh-agent-loop` | shipped `ReactLoopAgent` driver | ### Capability Services @@ -29,20 +29,20 @@ The default distribution is a composition, not a hierarchy. `packages/core/` is | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution | | `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events | | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries | -| `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-surface compaction | +| `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-log compaction | | `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | named delegation providers | | `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable storage for session logs | -## Event Surface +## Event -Events are the harness extension API. Each service owns the vocabulary for the behavior it controls, and the generated [events catalog](cordis-catalog/events.md) is the exhaustive reference. The [producer/consumer map](event-producer-consumer.md) shows which packages emit or listen to each event. +Events are the harness extension API used by Service. The generated [events catalog](cordis-catalog/events.md) is the exhaustive reference. The [producer/consumer map](event-producer-consumer.md) shows which packages emit or listen to each event. ### Event Domains Pick the event domain for new behavior: - **Session events** are durable, replayable facts. Turn and step boundaries, user input, assistant output, tool calls, tool results, steering, compaction records, and tool-owned durable facts append to the session log and flow through `session/event`. -- **Agent events** are live runtime surfaces. They carry the live `Agent` handle for status, diagnostics, prompt admission, call-config shaping, result validation, and continuation policy. +- **Agent events** carry the live `Agent` handle for status, diagnostics, prompt admission, call-config shaping, result validation, and continuation policy. - **Capability events** belong to the seam that owns the action. `tools/*`, `llm/*`, `system-prompt/*`, `fs/*`, and `subagent/*` let policy and adapters attach without importing the loop. ### Interception Semantics @@ -51,9 +51,9 @@ Waterfall events behave like around-middleware: a listener delegates by calling ## Default Loop Lifecycle -The shipped loop drains queued work, assembles a request, streams a model answer, executes tools, decides whether to continue, and checkpoints durable state. The important architecture is where it pauses: each pause is a documented service call or event seam other plugins program against. +The shipped loop drains queued work, assembles a request, streams a model answer, executes tools, decides whether to continue, and checkpoints durable state. The important part is where it pauses: each pause is a documented service call or event that another plugin can use. -A **session** is one agent's append-only event log. A **turn** drains one queued batch and runs until the model stops asking for tools and no plugin requests continuation. A **step** is one model request plus the tool executions caused by that response. In the flow below ([sequence companion](agent-lifecycle.md)), quoted names are durable session events and event names are extension seams. +A **session** is one agent's append-only event log. A **turn** drains one queued batch and runs until the model stops asking for tools and no plugin requests continuation. A **step** is one model request plus the tool executions caused by that response. In the flow below ([sequence companion](agent-lifecycle.md)), quoted names are durable session events and event names are extension points. ### Turn Flow @@ -102,9 +102,9 @@ Every session event is turn-enclosed. Reloading a crashed session preserves the ### Agent Handles -`ctx.agents` owns live agents and returns an `AgentHandle { agent, dispose() }`. `Agent` is the surface other plugins drive: `send()` queues work, `steer()` injects mid-turn content, `inject()` appends context and opens a one-shot injection turn when idle, `cancel()` is the public stop primitive, and `whenIdle()` observes quiescence. Lifecycle owners tear down with `await dispose()`. +`ctx.agents` owns live agents and returns an `AgentHandle { agent, dispose() }`. `Agent` is the API other plugins drive: `send()` queues work, `steer()` injects mid-turn content, `inject()` appends context and opens a one-shot injection turn when idle, `cancel()` is the public stop primitive, and `whenIdle()` observes quiescence. Lifecycle owners tear down with `await dispose()`. -## State And Model Surface +## State ### Session Log @@ -116,7 +116,7 @@ Durability is a plugin concern. Persistence backends buffer synchronous `session ### Model Content -Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, compaction pricing, and persistence, so block vocabulary remains a repo-wide contract. +Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, compaction pricing, and persistence, so block types remain a repo-wide contract. Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAssembler` as the shared chunk-to-block assembler. The loop logs raw chunks while assembling them for dispatch. `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register with `ctx.llm.registerAdapter(models, adapter)`. StreamChunk conventions live in [llm-streaming.md](core-data-structures/llm-streaming.md). @@ -124,17 +124,17 @@ Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAs ### Capability Pattern -A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and vocabulary; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability seam graph](capability-seams.md) shows the package families. +A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and event names; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability graph](capability-seams.md) shows the current package families. -Some seams bend the template deliberately. LLM keeps interface and consumer vocabulary together because adapters are the implementations. Filesystem adds policy as event gates around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Subagents use a named provider registry because multiple delegation backends can coexist; `spawn` starts fresh, `fork` seeds from the parent's completed-turn prefix, and ACP can drive an out-of-process child ([subagent.md](core-data-structures/subagent.md)). +Some cases bend the template deliberately. LLM keeps interface and consumer event names together because adapters are the implementations. Filesystem adds policy checks around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Subagents use a named provider registry because multiple delegation backends can coexist; `spawn` starts fresh, `fork` seeds from the parent's completed-turn prefix, and ACP can drive an out-of-process child ([subagent.md](core-data-structures/subagent.md)). ### Bundles And Apps -`dsh-agent-core` is the default composition bundle: one plugin loading the providerless spine as code ([README](../packages/core/agent-core/README.md)). App packages compose it with a front door and own the boot `bin`: `dsh-stdio-agent` for the terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)). +`dsh-agent-core` is the default bundle: one plugin loading the agent loop ([README](../packages/core/agent-core/README.md)). App packages compose it with a front end and own the entrypoint `bin`: `dsh-stdio-agent` for the terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)). ### Where New Behavior Goes -New behavior should attach to a documented seam; changing the shipped loop requires updating this map. +New behavior should attach to a documented extension point; changing the shipped loop requires updating this map. | Goal | Mechanism | |---|---| @@ -149,3 +149,10 @@ New behavior should attach to a documented seam; changing the shipped loop requi | Fork a live session | use `ctx.sessions.fork(source, boundary?, childSessionId?)` | The [extension cookbook](cookbook/extension-cookbook.md) carries plugin skeletons and the feature-to-seam map; step-by-step guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md). + +## Quick Reference +- Type definitions in [core-data-structures/](core-data-structures/core.md) +- Exact event and service signatures in [events](cordis-catalog/events.md) +- [services](cordis-catalog/services.md) catalogs +- package contracts in the [package map](../packages/README.md) +- [RFCs](rfc/README.md) \ No newline at end of file diff --git a/docs/cordis-primer.md b/docs/cordis-primer.md index 15534b0ae6..b59363eea7 100644 --- a/docs/cordis-primer.md +++ b/docs/cordis-primer.md @@ -4,35 +4,35 @@ Cordis is the vendored plugin framework underneath the DeepSeek Harness SDK. Thi ## Cordis In Five Ideas -- **A plugin is a unit of behavior.** It can be a function with optional `inject` and `apply(ctx)` fields, or a `Service` subclass whose lifecycle Cordis mounts into the current context. -- **A context is the service container.** A service claims a stable `ctx.` such as `ctx.tools`, `ctx.llm`, or `ctx.sessions`; other plugins program against that key instead of importing a concrete implementation. -- **`inject` is the dependency gate.** A plugin that names required services waits until those services exist, so load order is expressed through service requirements rather than manual boot sequencing. -- **Events are typed extension seams.** Services declare event names through TypeScript declaration merging, then dispatch them as `emit`, `waterfall`, `parallel`, or `serial` depending on whether listeners observe, wrap, fan out, or run in order. -- **Registrations are disposable effects.** Prompt sections, tool schemas, adapters, providers, and listeners are installed through `ctx.effect()` or `ctx.on()` so reload and teardown unwind them predictably. +- **A plugin is a object that implements Service.** It can be a function with optional `inject` and `apply(ctx)` fields, or a `Service` subclass whose lifecycle Cordis mounts into the current context. +- **A context is a repository of services.** A service claims a stable `ctx.` such as `ctx.tools`, `ctx.llm`, or `ctx.sessions` from a context; other plugins find services via key instead of importing a concrete implementation. +- **Declare service dependency via `inject`.** A plugin that names required services waits until those services exist, so load order is expressed through service requirements rather than manual boot sequencing. +- **Typed Events for communication.** Services declare event names through TypeScript declaration merging, then dispatch them as `emit`, `waterfall`, `parallel`, or `serial` depending on whether listeners observe, wrap, fan out, or run in order. +- **Registrations are reversible effects.** Prompt sections, tool schemas, adapters, providers, and listeners are installed through `ctx.effect()` or `ctx.on()` so reload and teardown unwind them predictably. ## Dispatch Modes -Use the mode to understand what a listener can do: +Every event can have one of the following dispatch mode and can only be dispatched by these methods accordingly. -| Mode | Shape | -|---|---| -| `emit` | synchronous notification; listeners observe but do not shape the result | -| `waterfall` | around-middleware; each listener receives `next()` and may wrap, rewrite, or veto | -| `parallel` | awaited fan-out; all listeners run and the dispatcher waits for them | -| `serial` | awaited in registration order; a non-void bail value stops the chain | +| Mode | Awaited? | Dispatch Order | Has Return Value? | +|---|---|---|---| +| `emit` | No | listeners observe in registration order | No | +| `waterfall` | No | listeners observe in registration order | Yes | +| `parallel` | Yes | all listeners observe the event in parallel | No | +| `serial` | Yes | listeners observe in registration order | Yes | The mode is part of the event's public contract. New harness events document it with an `@mode` tag so the generated catalog can check declarations against dispatch sites. ## Cordis Waterfall Semantics -`ctx.waterfall` is around-middleware, not a reducer. A listener receives `(...args, next)`. Call `next()` to delegate, optionally wrapping the result; return without `next()` to short-circuit. Values propagate through `next()`'s return value. +`ctx.waterfall` is around-middleware. A listener receives `(...args, next)`. Call `next()` to delegate the possibly wrapped result to the next service; return without `next()` to short-circuit. Values propagate through `next()`'s return value. -Cooperative listeners usually mutate a shared request or decision object and then delegate. Returning a replacement is a takeover: downstream listeners see the replacement, and earlier mutations on the original object do not carry forward. Use `prepend: true` only when the listener must run before ordinary registrations. +Cooperative listeners usually mutate a shared request or decision object and then delegate. A listener can also choose to repalce the result entirely and downstream listeners will only see the result after replacement. Use `prepend: true` only when the listener must run before ordinary registrations. For single-decision events, short-circuiting is the design. A policy listener can return without `next()` when it owns the decision, while a listener that only annotates or observes must delegate. ## Practical Rules -Own vocabulary where the behavior lives: a tool pipeline event belongs to `ctx.tools`, model streaming belongs to `ctx.llm`, and live agent coordination belongs to `ctx.agents`. Prefer events for interception and policy; prefer service methods for direct capability calls. +Encapsulate behavior into plugins: a tool pipeline event belongs to `ctx.tools`, model streaming belongs to `ctx.llm`, and live agent coordination belongs to `ctx.agents`. Prefer events for interception and policy; prefer service methods for direct capability calls. Every registration should have a disposer, either by returning one from `ctx.effect()` or using a Cordis helper that does it for you. If teardown order matters, keep the related work in one effect so disposal unwinds in the intended sequence. From d12cb45838b394c1af75f2fbc3e379f4e2fb6c99 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 23:46:19 +0800 Subject: [PATCH 113/119] workflow: spawn the worker with an empty environment The documented vm escape reaches process, and the worker inherited the harness's env - so a buggy or prompt-injected script could read and exfiltrate ambient credentials (DEEPSEEK_API_KEY et al.) without touching a single file (ds-review-bot finding on #233). Spawn with env: {} and a hermetic execArgv on both runtime shapes, the same stance as dsh-code-runtime-worker and stronger than the scrubbed env the defensive-patterns rule requires for spawned commands (a shell needs PATH; this worker needs nothing). Ambient-channel hardening only: an escapee keeps the process-wide privileges the trust premise already admits - the genuine sandbox remains an engine swap. --- .../workflow/workflow-workerthread/README.md | 1 + .../workflow/workflow-workerthread/src/host.ts | 16 +++++++++++++--- .../tests/workflow-workerthread.spec.ts | 18 ++++++++++++++++++ 3 files changed, 32 insertions(+), 3 deletions(-) diff --git a/packages/workflow/workflow-workerthread/README.md b/packages/workflow/workflow-workerthread/README.md index 2d98273ae0..2c556fc35d 100644 --- a/packages/workflow/workflow-workerthread/README.md +++ b/packages/workflow/workflow-workerthread/README.md @@ -8,6 +8,7 @@ Workflow scripts are **model-written** — the same trust level as the model's e - **The host never blocks**: `start()` returns without running any script code on the host; a synchronous spin anywhere in the script occupies the worker's loop, not the harness's. - **Termination is real**: a script that outlives its post-cancel grace is `worker.terminate()`d — nothing of it survives `dispose()`, where an in-process engine could only abandon the spin on its own loop. +- **No ambient credentials**: the worker spawns with an EMPTY environment (`env: {}` plus hermetic `execArgv`, the same stance as `dsh-code-runtime-worker`), so an escapee reading `process.env` finds no harness secrets — ambient-channel hardening only; the process-wide privileges above (fs and the rest) remain, so a genuine sandbox is still the engine swap. - **Serialization by construction**: everything crossing the thread is structured-clone data, and plain JSON before that — the `materializeFromRealm` walk rejects loud what JSON cannot carry, which is also what makes every postMessage hop total. What the seam guarantees regardless, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection, values JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing (containing what an escaped script may touch) remains an isolated-vm/separate-process engine swap behind the seam, still deferred. diff --git a/packages/workflow/workflow-workerthread/src/host.ts b/packages/workflow/workflow-workerthread/src/host.ts index 28db34f097..9f39cd80e4 100644 --- a/packages/workflow/workflow-workerthread/src/host.ts +++ b/packages/workflow/workflow-workerthread/src/host.ts @@ -56,20 +56,30 @@ import type { ChildStartRequest, WorkerInit } from './types.ts' * vitest (vite transforms in-process, not via a node loader), and passing * execArgv explicitly also shields the worker from any loader flags the * parent was started with. Built (`lib/index.js`), the entry is the sibling - * bundle the package tsdown config emits and no loader is needed. + * bundle the package tsdown config emits and no loader is needed (execArgv + * pinned empty — hermetic, like the environment). + * + * Both shapes spawn with an EMPTY environment (`env: {}`): the documented vm + * escape reaches `process`, and the harness's ambient credentials + * (`DEEPSEEK_API_KEY` et al.) must not ride along — the same stance as + * `dsh-code-runtime-worker`, stronger than the scrubbed env the + * defensive-patterns rule requires for spawned commands (a shell needs PATH; + * this worker needs nothing). This closes the AMBIENT channel only — an + * escapee still holds process-wide privileges like fs access (the README's + * trust premise stands). * @param init - the run payload, passed as `workerData`. * @returns the entry URL and the Worker options to spawn it with. */ function resolveWorkerSpawn(init: WorkerInit): { entry: URL; options: WorkerOptions } { /* v8 ignore next 3 -- the built-output arm: tests always run unbuilt (src/); the built-worker e2e exercises this shape for real */ if (!import.meta.url.endsWith('.ts')) { - return { entry: new URL('./worker.js', import.meta.url), options: { workerData: init } } + return { entry: new URL('./worker.js', import.meta.url), options: { workerData: init, env: {}, execArgv: [] } } } // Lazy tsx resolution: only the unbuilt shape needs it, so the built // bundle never requires tsx to be installed. return { entry: new URL('./worker.ts', import.meta.url), - options: { workerData: init, execArgv: ['--import', fileURLToPath(import.meta.resolve('tsx'))] }, + options: { workerData: init, env: {}, execArgv: ['--import', fileURLToPath(import.meta.resolve('tsx'))] }, } } diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index eb50ec1121..32f63a6c97 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -254,6 +254,24 @@ describe('dsh-workflow-workerthread', () => { expect(result.stopReason).toBe('completed') expect(result.value).toBe('fine') }) + + it('the worker spawns with an EMPTY environment: an escaped script finds no ambient credentials', async () => { + const { ctx, parent } = await setup() + // A canary in the HARNESS process's env: with an inherited environment + // the escape below would read it back (exactly how DEEPSEEK_API_KEY + // would leak); env: {} in the spawn options is what keeps it out. + process.env.WORKFLOW_ENV_CANARY = 'leak me' + try { + const result = await run(ctx, parent, scripted(` + const proc = ${ESCAPE} + return { canary: proc.env.WORKFLOW_ENV_CANARY ?? null, keys: Object.keys(proc.env).length } + `)) + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ canary: null, keys: 0 }) + } finally { + delete process.env.WORKFLOW_ENV_CANARY + } + }) }) describe('lifecycle: parse errors, cancellation, termination, disposal', () => { From f77174f13a52475d381eb9959ba2cc6ab8c499f0 Mon Sep 17 00:00:00 2001 From: Turtle Date: Fri, 10 Jul 2026 00:13:06 +0800 Subject: [PATCH 114/119] make it clearer --- docs/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 118c535874..a6e3c7236c 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -35,7 +35,7 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How ## Wordcount Budgets -Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure, which lists the word count of each standing docs; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. +Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure: it stores the allowed word-count ceiling for each budgeted standing doc; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. - Ceilings are an enforcement frontier with working headroom: a ceiling sits at least 5% above the doc's current size — routine edits pass, real growth trips the gate — and ratchets down, keeping the margin, as the doc reaches target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600. - When the gate goes red, first ask whether the added words belong in this tier and whether the existing wording can be condensed. If the words do not belong, relocate per the taxonomy above; if they belong but can be shorter, condense. If they truly need the space, raise the ceiling and justify the manifest diff in the PR. A ceiling set too low is a budget bug, and correcting it is the fix. From aff657cc2823ae7a8e85446e668aa9d0afd88190 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 10 Jul 2026 00:16:29 +0800 Subject: [PATCH 115/119] fix: ci run without build lib for snapshot --- .../workflow/workflow-workerthread/README.md | 2 +- .../workflow-workerthread/src/host.ts | 21 ++++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/packages/workflow/workflow-workerthread/README.md b/packages/workflow/workflow-workerthread/README.md index 2c556fc35d..1ee959cc0c 100644 --- a/packages/workflow/workflow-workerthread/README.md +++ b/packages/workflow/workflow-workerthread/README.md @@ -8,7 +8,7 @@ Workflow scripts are **model-written** — the same trust level as the model's e - **The host never blocks**: `start()` returns without running any script code on the host; a synchronous spin anywhere in the script occupies the worker's loop, not the harness's. - **Termination is real**: a script that outlives its post-cancel grace is `worker.terminate()`d — nothing of it survives `dispose()`, where an in-process engine could only abandon the spin on its own loop. -- **No ambient credentials**: the worker spawns with an EMPTY environment (`env: {}` plus hermetic `execArgv`, the same stance as `dsh-code-runtime-worker`), so an escapee reading `process.env` finds no harness secrets — ambient-channel hardening only; the process-wide privileges above (fs and the rest) remain, so a genuine sandbox is still the engine swap. +- **No ambient credentials**: the worker spawns with an EMPTY environment (`env: {}` plus hermetic `execArgv`, the same stance as `dsh-code-runtime-worker`; the unbuilt dev shape forwards exactly one loader variable, `TSX_TSCONFIG_PATH` — path plumbing, not a secret), so an escapee reading `process.env` finds no harness secrets — ambient-channel hardening only; the process-wide privileges above (fs and the rest) remain, so a genuine sandbox is still the engine swap. - **Serialization by construction**: everything crossing the thread is structured-clone data, and plain JSON before that — the `materializeFromRealm` walk rejects loud what JSON cannot carry, which is also what makes every postMessage hop total. What the seam guarantees regardless, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection, values JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing (containing what an escaped script may touch) remains an isolated-vm/separate-process engine swap behind the seam, still deferred. diff --git a/packages/workflow/workflow-workerthread/src/host.ts b/packages/workflow/workflow-workerthread/src/host.ts index 9f39cd80e4..6b6391a02e 100644 --- a/packages/workflow/workflow-workerthread/src/host.ts +++ b/packages/workflow/workflow-workerthread/src/host.ts @@ -64,9 +64,11 @@ import type { ChildStartRequest, WorkerInit } from './types.ts' * (`DEEPSEEK_API_KEY` et al.) must not ride along — the same stance as * `dsh-code-runtime-worker`, stronger than the scrubbed env the * defensive-patterns rule requires for spawned commands (a shell needs PATH; - * this worker needs nothing). This closes the AMBIENT channel only — an - * escapee still holds process-wide privileges like fs access (the README's - * trust premise stands). + * this worker needs nothing). Sole exception: the unbuilt shape forwards + * `TSX_TSCONFIG_PATH` when the parent carries it (loader plumbing the paths + * map depends on outside the repo cwd, not a secret). This closes the + * AMBIENT channel only — an escapee still holds process-wide privileges + * like fs access (the README's trust premise stands). * @param init - the run payload, passed as `workerData`. * @returns the entry URL and the Worker options to spawn it with. */ @@ -76,10 +78,19 @@ function resolveWorkerSpawn(init: WorkerInit): { entry: URL; options: WorkerOpti return { entry: new URL('./worker.js', import.meta.url), options: { workerData: init, env: {}, execArgv: [] } } } // Lazy tsx resolution: only the unbuilt shape needs it, so the built - // bundle never requires tsx to be installed. + // bundle never requires tsx to be installed. TSX_TSCONFIG_PATH is the one + // variable forwarded through the scrub: tsx finds a tsconfig by searching + // UP from the worker's cwd, and a parent running with its cwd outside the + // repo (the ACP snapshot harness pins the tsconfig through this exact + // variable) would otherwise lose the dsh-* paths map and resolve workspace + // imports to unbuilt lib/ bundles. Loader plumbing, not a secret. return { entry: new URL('./worker.ts', import.meta.url), - options: { workerData: init, env: {}, execArgv: ['--import', fileURLToPath(import.meta.resolve('tsx'))] }, + options: { + workerData: init, + env: process.env.TSX_TSCONFIG_PATH === undefined ? {} : { TSX_TSCONFIG_PATH: process.env.TSX_TSCONFIG_PATH }, + execArgv: ['--import', fileURLToPath(import.meta.resolve('tsx'))], + }, } } From c60eb878601f54ee5a9d32496c7e2237a49643b0 Mon Sep 17 00:00:00 2001 From: Turtle Date: Fri, 10 Jul 2026 00:20:35 +0800 Subject: [PATCH 116/119] make wordcount budget guidance clearer and dedup docs --- .agents/skills/dsh-doc-standards/SKILL.md | 4 +--- docs/AGENTS.md | 12 ++++++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md index 7c396ed93c..de7eda4142 100644 --- a/.agents/skills/dsh-doc-standards/SKILL.md +++ b/.agents/skills/dsh-doc-standards/SKILL.md @@ -38,9 +38,7 @@ Compression discipline: every load-bearing rule survives — as one to three lin ## When verify-doc-budgets goes red -1. Relocate: does the new content belong in a linked home (RFC, postmortem, cookbook, README) with a one-line pointer left behind? -2. Condense: can existing prose in the doc pay for the addition — a story compressed to its rule, a duplicate converted to a link? -3. Only then raise the ceiling: edit `scripts/doc-budgets.manifest.json` and justify the raise explicitly in the PR description. After any rewrite that shrinks a budgeted doc, ratchet its ceiling down to the new size plus working headroom (at least 5%) in the same PR. +Apply the ordered relocate-condense-raise policy in [docs/AGENTS.md](../../../docs/AGENTS.md); this skill only supplies the workflow probes above. ## Validation and PR hygiene diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a6e3c7236c..6824c71cc6 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -35,11 +35,15 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How ## Wordcount Budgets -Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure: it stores the allowed word-count ceiling for each budgeted standing doc; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. +Every PR has a lesson it wants to append, and without pressure nothing leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) stores the allowed word-count ceiling for each budgeted standing doc; `pnpm run verify-doc-budgets` fails when a doc exceeds its ceiling or a budgeted file is missing. -- Ceilings are an enforcement frontier with working headroom: a ceiling sits at least 5% above the doc's current size — routine edits pass, real growth trips the gate — and ratchets down, keeping the margin, as the doc reaches target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600. -- When the gate goes red, first ask whether the added words belong in this tier and whether the existing wording can be condensed. If the words do not belong, relocate per the taxonomy above; if they belong but can be shorter, condense. If they truly need the space, raise the ceiling and justify the manifest diff in the PR. A ceiling set too low is a budget bug, and correcting it is the fix. -- Unbudgeted tiers (package READMEs, RFCs, reference matrices) have no ceiling — length is legitimate there when every row is a fact. Review and the slop checklist govern them instead. +When the gate goes red: + +1. **Relocate** content that belongs in another tier; leave a one-line link if needed. +2. **Condense** content that belongs here but can be shorter. +3. **Raise** the ceiling only when the words truly need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug. + +Ceilings keep working headroom: at least 5% above the current size, ratcheted down after trims. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file ≤ 1,250; `packages/README.md` ≤ 600. Unbudgeted tiers (package READMEs, RFCs, reference matrices) have no ceiling; review and the slop checklist govern them. ## The slop checklist From a53be53d64732cf3ded39bb4fd008b78e5c076aa Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 10 Jul 2026 00:23:11 +0800 Subject: [PATCH 117/119] workflow: forward TSX_TSCONFIG_PATH through the worker env scrub The empty-env hardening wiped the one variable the UNBUILT worker's loader depends on: tsx finds a tsconfig by searching up from the worker's cwd, and a parent running outside the repo (the ACP snapshot harness pins the repo tsconfig through TSX_TSCONFIG_PATH exactly because its child cwd is a temp dir) lost the dsh-* paths map - the worker then resolved workspace imports to unbuilt lib/ bundles and died on CI with ERR_MODULE_NOT_FOUND (green locally only because stale built lib/ masked the wrong resolution). Forward exactly that variable when the parent carries it - loader plumbing, not a secret; the built shape stays fully empty - and pin the whole contract with an escape-based test: the worker env is exactly {TSX_TSCONFIG_PATH}, the credential canary still never crosses. --- .../tests/workflow-workerthread.spec.ts | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index 32f63a6c97..ecaeed61f6 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -1,4 +1,5 @@ import { describe, expect, it, vi } from 'vitest' +import { fileURLToPath } from 'node:url' import { Context } from 'cordis' import Loader from '@cordisjs/plugin-loader' import { AgentId } from '@deepseek-ai/dsh-agent' @@ -272,6 +273,28 @@ describe('dsh-workflow-workerthread', () => { delete process.env.WORKFLOW_ENV_CANARY } }) + + it('the unbuilt worker forwards exactly TSX_TSCONFIG_PATH through the scrub: the paths-map pin survives, secrets do not', async () => { + const { ctx, parent } = await setup() + // The ACP snapshot harness runs the parent with its cwd OUTSIDE the + // repo and pins the repo tsconfig through this variable; the worker + // must inherit the pin (or its dsh-* imports silently resolve to + // unbuilt lib/ bundles) while every other variable stays scrubbed. + const tsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) + process.env.TSX_TSCONFIG_PATH = tsconfig + process.env.WORKFLOW_ENV_CANARY = 'leak me' + try { + const result = await run(ctx, parent, scripted(` + const proc = ${ESCAPE} + return { keys: Object.keys(proc.env), tsconfig: proc.env.TSX_TSCONFIG_PATH } + `)) + expect(result.stopReason).toBe('completed') + expect(result.value).toEqual({ keys: ['TSX_TSCONFIG_PATH'], tsconfig }) + } finally { + delete process.env.TSX_TSCONFIG_PATH + delete process.env.WORKFLOW_ENV_CANARY + } + }) }) describe('lifecycle: parse errors, cancellation, termination, disposal', () => { From 64b4e2ed2db6d5a27c1266b5c8bd97c8532929b1 Mon Sep 17 00:00:00 2001 From: pku-xht Date: Fri, 10 Jul 2026 16:43:41 +0800 Subject: [PATCH 118/119] test(workflow-workerthread): flake-proof the lifecycle spec's waits under CI load MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The spec's 16 vi.waitFor sites used the 1s default timeout to wait for worker-thread startup and child registration — CPU-bound work that blows past 1s on a contended runner. The CI coverage lane (4 vitest workers plus suites that spawn real subprocesses) hit this 3 times across 4 recent PR runs, each a different subset of the cancellation/worker-death tests, each green on rerun. Every wait now goes through a shared helper with a 10s bound, and the file sets a 30s test timeout to make room for it. The one deliberately tight wait keeps its 800ms bound through the helper's override — it proves the host (not the wedged worker's later loop turn) delivered the cancel, so a generous bound would erase what it tests. No behavior under test changed. --- .../tests/workflow-workerthread.spec.ts | 52 +++++++++++++------ 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index ecaeed61f6..175a82a7b9 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -15,6 +15,26 @@ function fakeParent(): Agent { return { id: AgentId('workflow-parent'), options: {} } as unknown as Agent } +// Worker-thread startup is CPU-bound (a fresh thread compiles the runtime on +// every start): on a contended CI runner it regularly blows past vitest's 5s +// default test timeout, observed repeatedly on the coverage lane. +vi.setConfig({ testTimeout: 30_000 }) + +/** + * `vi.waitFor` with a contention-proof timeout: the 1s default flaked + * repeatedly on the CI coverage lane, where worker-thread cold start competes + * with three sibling vitest workers for CPU. Every wait in this file is for + * something that WILL happen (a worker starting, a child registering) — a + * generous bound only removes the flake, it cannot mask a genuine hang (the + * file-wide test timeout above still fences those). + * @param assertion - retried until it stops throwing or the timeout elapses. + * @param timeout - override for a wait that must stay deliberately tight. + * @returns resolves when the assertion passes. + */ +function waitFor(assertion: () => void, timeout = 10_000): Promise { + return vi.waitFor(assertion, { timeout, interval: 50 }) +} + /** The vm-context escape hatch, spelled once: real Worker tests use it to make the WORKER misbehave. */ const ESCAPE = "globalThis.constructor.constructor('return process')()" @@ -316,7 +336,7 @@ describe('dsh-workflow-workerthread', () => { const runEnds: WorkflowResultInfo[] = [] ctx.on('workflow/end', (_info, result) => { runEnds.push(result) }) const handle = ctx.workflows.start({ ...scripted("return await agent('long job')"), parent }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) handle.cancel('user stopped it') const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -357,7 +377,7 @@ describe('dsh-workflow-workerthread', () => { const controller = new AbortController() const second = ctx.workflows.start({ ...scripted("return await agent('job')"), parent, signal: controller.signal }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) controller.abort() expect((await second.result).stopReason).toBe('cancelled') await second.dispose() @@ -400,7 +420,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(narration).toContain('started') }) + await waitFor(() => { expect(narration).toContain('started') }) handle.cancel('raced the completion') const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -480,7 +500,7 @@ describe('dsh-workflow-workerthread', () => { }) const result = await handle.result expect(result.stopReason).toBe('completed') - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) await handle.dispose() // Not a waitFor: by the time dispose() returns, the slow child disposal // must already be complete (host-side registry quiescence). @@ -526,7 +546,7 @@ describe('dsh-workflow-workerthread', () => { expect(result.stopReason).toBe('completed') // BEFORE dispose(): the settlement itself must have aborted the signal — // without it this child would stay live until dispose's terminate. - await vi.waitFor(() => { expect(aborted).toEqual(['workflow settled']) }) + await waitFor(() => { expect(aborted).toEqual(['workflow settled']) }) await handle.dispose() }) @@ -572,9 +592,9 @@ describe('dsh-workflow-workerthread', () => { `), parent: fakeParent(), }) - await vi.waitFor(() => { expect(starts).toBe(1) }) + await waitFor(() => { expect(starts).toBe(1) }) handle.cancel('stop now') - await vi.waitFor(() => { expect(cancelled).toEqual(['stop now']) }, { timeout: 800 }) + await waitFor(() => { expect(cancelled).toEqual(['stop now']) }, 800) // The wedged worker's own completion loses to the in-flight cancel. const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -602,7 +622,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) const before = Date.now() await handle.dispose() // Bounded by the grace (plus the terminate), never by the 1.5s spin. @@ -625,7 +645,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(1) }) + await waitFor(() => { expect(provider.runs.length).toBe(1) }) const handleDispose = handle.dispose() const result = await handle.result // The script itself settled (the wrapper's own dispose RPC found the @@ -663,7 +683,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) + await waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')! fast.settle(text('fast done')) handle.cancel('stop now') @@ -694,7 +714,7 @@ describe('dsh-workflow-workerthread', () => { ...scripted("await parallel([() => agent('a'), () => agent('b')])\nreturn 'unreachable'"), parent, }) - await vi.waitFor(() => { expect(provider.runs.length).toBe(2) }) + await waitFor(() => { expect(provider.runs.length).toBe(2) }) handle.cancel('user stop') const result = await handle.result expect(result.stopReason).toBe('cancelled') @@ -749,7 +769,7 @@ describe('dsh-workflow-workerthread', () => { // A worker death is a stop reason like any other: workflow/end fires // with the error outcome — for a bus observer it is the only obituary. expect(runEnds).toEqual([{ stopReason: 'error', error: result.error, agentsStarted: 1 }]) - await vi.waitFor(() => { expect(cancelled.length).toBe(1) }) + await waitFor(() => { expect(cancelled.length).toBe(1) }) await handle.dispose() }, 15_000) @@ -770,7 +790,7 @@ describe('dsh-workflow-workerthread', () => { expect(result.stopReason).toBe('error') expect(result.error).toContain('worker blew up') // The reap wound the stray child down (cancel + a CLEAN dispose). - await vi.waitFor(() => { + await waitFor(() => { expect(provider.runs.length).toBe(1) expect(provider.runs[0]!.disposed).toBe(true) }) @@ -802,7 +822,7 @@ describe('dsh-workflow-workerthread', () => { `), parent, }) - await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) + await waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) }) const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')! fast.settle(text('fast done')) const result = await handle.result @@ -837,7 +857,7 @@ describe('dsh-workflow-workerthread', () => { const result = await handle.result expect(result.stopReason).toBe('error') expect(result.error).toContain('exit code 5') - await vi.waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }) + await waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }) await handle.dispose() }, 15_000) @@ -855,7 +875,7 @@ describe('dsh-workflow-workerthread', () => { }) const logs: string[] = [] ctx.on('workflow/log', (_info, message) => { logs.push(message) }) - await vi.waitFor(() => { expect(logs).toContain('armed') }) + await waitFor(() => { expect(logs).toContain('armed') }) handle.cancel('stop it') // The grace is deliberately huge: only the worker's own death (exit 3, // unreachable by the cancel — the script ignores hooks) settles this. From dd2f37b80fa1e69403268f02bd64b4576daa01f8 Mon Sep 17 00:00:00 2001 From: pku-xht Date: Fri, 10 Jul 2026 20:48:14 +0800 Subject: [PATCH 119/119] fix(workflow-workerthread): tighten post-result promptness waits back down MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-up: the blanket 10s default correctly targets worker-thread cold-start races (starting, first-script-line, async child-registration messages — genuinely CPU-bound under CI contention), but four waits assert something different — that the HOST reacted PROMPTLY to an event that already happened (a settled result, an observed worker death). Those had no cold-start left to wait on, so the generous default just widened the window a real regression could hide in. Verified by injecting a 6s delay into the settle-reap's abort call: the un-overridden helper's test still passed in ~6s. The same mutation now fails in ~1s with the explicit 1000ms override restored on all four sites (the abort-on-settle test's own assertion, the two worker-death cancel/dispose reap checks, and the dispose-ack-race check). The other 12 waits keep the 10s default — they run BEFORE a result is awaited, waiting on the worker to actually start rather than on a host reaction. Doc comment corrected to describe the split instead of claiming every wait is a cold-start race. --- .../tests/workflow-workerthread.spec.ts | 38 +++++++++++++------ 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts index 175a82a7b9..75a0b5116e 100644 --- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts +++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts @@ -21,12 +21,18 @@ function fakeParent(): Agent { vi.setConfig({ testTimeout: 30_000 }) /** - * `vi.waitFor` with a contention-proof timeout: the 1s default flaked - * repeatedly on the CI coverage lane, where worker-thread cold start competes - * with three sibling vitest workers for CPU. Every wait in this file is for - * something that WILL happen (a worker starting, a child registering) — a - * generous bound only removes the flake, it cannot mask a genuine hang (the - * file-wide test timeout above still fences those). + * `vi.waitFor` with a contention-proof default timeout: the 1s default + * flaked repeatedly on the CI coverage lane, where worker-thread cold start + * (CPU-bound — a fresh thread compiles the runtime) competes with three + * sibling vitest workers for CPU. The 10s default is for exactly those + * races — waiting for a worker to start, run its first script line, or + * deliver an async child-registration message to the host. It is NOT for a + * wait that asserts the HOST reacted PROMPTLY to something that already + * happened (a settled result, an observed worker death): those keep an + * explicit tight override below, or the generous default would silently + * accept a multi-second regression in host-side reap latency as passing + * (proven by injecting a 6s delay into one such reap and watching the + * un-overridden version of this helper still pass in ~6s). * @param assertion - retried until it stops throwing or the timeout elapses. * @param timeout - override for a wait that must stay deliberately tight. * @returns resolves when the assertion passes. @@ -545,8 +551,11 @@ describe('dsh-workflow-workerthread', () => { const result = await handle.result expect(result.stopReason).toBe('completed') // BEFORE dispose(): the settlement itself must have aborted the signal — - // without it this child would stay live until dispose's terminate. - await waitFor(() => { expect(aborted).toEqual(['workflow settled']) }) + // without it this child would stay live until dispose's terminate. This + // is a HOST-PROMPTNESS claim, not a cold-start race — a tight explicit + // bound (unlike the file default) so a multi-second reap regression + // cannot pass by outlasting the wait. + await waitFor(() => { expect(aborted).toEqual(['workflow settled']) }, 1000) await handle.dispose() }) @@ -769,7 +778,9 @@ describe('dsh-workflow-workerthread', () => { // A worker death is a stop reason like any other: workflow/end fires // with the error outcome — for a bus observer it is the only obituary. expect(runEnds).toEqual([{ stopReason: 'error', error: result.error, agentsStarted: 1 }]) - await waitFor(() => { expect(cancelled.length).toBe(1) }) + // Result already settled — this is the reap's promptness, not a + // cold-start race; tight explicit bound (see the helper's doc comment). + await waitFor(() => { expect(cancelled.length).toBe(1) }, 1000) await handle.dispose() }, 15_000) @@ -790,10 +801,12 @@ describe('dsh-workflow-workerthread', () => { expect(result.stopReason).toBe('error') expect(result.error).toContain('worker blew up') // The reap wound the stray child down (cancel + a CLEAN dispose). + // Result already settled — this is the reap's promptness, not a + // cold-start race; tight explicit bound (see the helper's doc comment). await waitFor(() => { expect(provider.runs.length).toBe(1) expect(provider.runs[0]!.disposed).toBe(true) - }) + }, 1000) await handle.dispose() }, 15_000) @@ -857,7 +870,10 @@ describe('dsh-workflow-workerthread', () => { const result = await handle.result expect(result.stopReason).toBe('error') expect(result.error).toContain('exit code 5') - await waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }) + // Result already settled — this is the reap's promptness (bounded + // above the mock's fixed 300ms dispose delay, not a cold-start race); + // tight explicit bound (see the helper's doc comment). + await waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) }, 1000) await handle.dispose() }, 15_000)